@adaas/a-frame 0.1.1 → 0.1.2

package/examples/structure/server-app.components.ts

@@ -0,0 +1,387 @@
+/**
+ * Server-application domain components.
+ *
+ * ~50 classes covering the full stack of a typical Node.js backend:
+ * HTTP infrastructure, auth, routing, CRUD services, jobs, event bus,
+ * caching, file storage, email, observability, and domain entities.
+ *
+ * All classes are registered under the "server-app" namespace so the
+ * A_FrameIndex scopes searches and the component mapper resolves
+ * architecture elements to concrete implementations.
+ */
+
+import { A_Component, A_Entity, A_Fragment } from '@adaas/a-concept';
+import { A_Frame } from '@adaas/a-frame/core';
+
+export const SERVER_APP_NAMESPACE = 'server-app';
+
+// ─── HTTP Infrastructure ──────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'The root HTTP server component. Initialises the Express application, attaches global middleware, binds the port, and manages graceful shutdown lifecycle.',
+})
+export class HttpServer extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Routes incoming HTTP requests to the correct controller handlers. Registers versioned route groups, applies per-route middleware, and validates HTTP method and path patterns.',
+})
+export class Router extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Processes raw HTTP requests before they reach controllers: parses JSON/form bodies, sets CORS headers, attaches request IDs, and enforces payload size limits.',
+})
+export class RequestMiddleware extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Intercepts outgoing HTTP responses to inject standard headers, sanitise error payloads, log response times, and enforce consistent JSON envelope structure.',
+})
+export class ResponseMiddleware extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Catches unhandled errors and uncaught promise rejections in the Express pipeline, formats them into structured JSON error responses, and logs stack traces.',
+})
+export class ErrorHandler extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Enforces per-IP and per-user request rate limits using a sliding-window algorithm. Returns 429 responses when thresholds are exceeded and logs abuse events.',
+})
+export class RateLimiter extends A_Component {}
+
+// ─── Auth & Security ──────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Handles user authentication: validates credentials, issues JWT access and refresh tokens, revokes sessions, and verifies token signatures on protected routes.',
+})
+export class AuthService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Manages role-based and attribute-based access control. Checks whether the authenticated principal has permission to perform a given action on a given resource.',
+})
+export class PermissionService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Generates, signs, and verifies JSON Web Tokens. Encodes user identity and claims into access tokens and validates incoming tokens on each request.',
+})
+export class JwtService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Hashes passwords using bcrypt or Argon2 before storage and verifies plain-text passwords against stored hashes during login.',
+})
+export class PasswordService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Validates HTTPS certificates for outbound service-to-service calls, manages TLS context configuration, and enforces certificate pinning policies.',
+})
+export class TlsService extends A_Component {}
+
+// ─── API Controllers ──────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Handles all user-facing HTTP endpoints: register, login, logout, get profile, update profile, and delete account. Delegates business logic to UserService.',
+})
+export class UserController extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Handles HTTP endpoints for authentication flows: POST /auth/login, POST /auth/refresh, POST /auth/logout, POST /auth/forgot-password, POST /auth/reset-password.',
+})
+export class AuthController extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Handles CRUD HTTP endpoints for the core domain resource. Validates request bodies, calls the corresponding service method, and returns structured responses.',
+})
+export class ResourceController extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Handles file upload and download HTTP endpoints. Validates MIME types and sizes, streams files to object storage, and returns signed download URLs.',
+})
+export class FileController extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Handles health-check and readiness-probe endpoints. Returns liveness and readiness status, database ping results, and uptime metrics for orchestrators.',
+})
+export class HealthController extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Handles webhook ingestion endpoints. Verifies HMAC signatures, parses event payloads, routes events to the appropriate handler, and returns 200 acknowledgements.',
+})
+export class WebhookController extends A_Component {}
+
+// ─── Business Services ────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Encapsulates all user domain logic: creating accounts, updating profiles, searching users, soft-deleting accounts, and emitting domain events on state changes.',
+})
+export class UserService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Manages the subscription and billing lifecycle: creating plans, processing payments, upgrading or downgrading tiers, and handling failed-payment retries.',
+})
+export class SubscriptionService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Sends transactional emails (welcome, password reset, invoice, notification) via a third-party provider such as SendGrid or SES, with template rendering and retry logic.',
+})
+export class EmailService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Sends mobile push notifications through APNs and FCM. Manages device token registration, batch delivery, and delivery receipt tracking.',
+})
+export class PushNotificationService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Manages in-app notifications: creating notification records, marking them as read, querying unread counts, and broadcasting real-time updates over WebSocket.',
+})
+export class NotificationService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Orchestrates file uploads and downloads: receives multipart requests, validates content, uploads binaries to object storage, and records metadata in the database.',
+})
+export class FileStorageService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Handles search queries across the application. Builds search requests, queries the search index (e.g. Elasticsearch or Meilisearch), and returns ranked results.',
+})
+export class SearchService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Validates incoming request data against compiled schemas. Returns structured validation errors with field paths and human-readable messages.',
+})
+export class ValidationService extends A_Component {}
+
+// ─── Data Access ──────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Manages the database connection pool, executes queries, handles transactions, and maps raw result rows to domain entity objects.',
+})
+export class DatabaseService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Provides typed read/write access to the User table. Implements findById, findByEmail, create, update, softDelete, and paginated list queries.',
+})
+export class UserRepository extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Provides typed read/write access to the core domain resource table. Implements CRUD, soft-delete, and filtered list queries with sorting and pagination.',
+})
+export class ResourceRepository extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Reads from and writes to Redis. Provides get, set, setex, del, and key-pattern scan. Used for caching, session storage, and distributed locks.',
+})
+export class CacheService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Manages database schema migrations: applies pending migration scripts, records migration history, and supports rolling back the last applied migration.',
+})
+export class MigrationService extends A_Component {}
+
+// ─── Event Bus & Messaging ────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Publishes domain events to a message broker (RabbitMQ, Kafka, or Redis Streams). Serialises event payloads, applies routing keys, and ensures at-least-once delivery.',
+})
+export class EventBus extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Subscribes to domain events from a message broker. Deserialises payloads, dispatches events to registered handlers, and acknowledges processed messages.',
+})
+export class EventConsumer extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Manages WebSocket connections: authenticates upgrade requests, tracks connected clients per room, broadcasts messages, and cleans up disconnected sockets.',
+})
+export class WebSocketService extends A_Component {}
+
+// ─── Scheduled Jobs ───────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Schedules and runs recurring background jobs using cron expressions. Registers job handlers, fires jobs on schedule, and logs execution durations and errors.',
+})
+export class Cron extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Runs the daily cleanup job: purges expired sessions, deletes soft-deleted records older than the retention window, and vacuums orphaned file references.',
+})
+export class CleanupJob extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Sends digest emails to users on a configurable schedule. Aggregates recent activity, renders the email template, and enqueues messages via EmailService.',
+})
+export class DigestJob extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Processes items from a work queue (database or Redis). Picks up pending tasks, executes them with retry logic and backoff, and records results.',
+})
+export class QueueWorker extends A_Component {}
+
+// ─── Observability ────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Structured application logger. Writes JSON log lines to stdout/stderr with log level, correlation ID, service name, and arbitrary metadata fields.',
+})
+export class Logger extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Collects and exposes Prometheus-compatible metrics: HTTP request durations, error rates, queue depths, and custom business counters.',
+})
+export class MetricsService extends A_Component {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Instruments outbound calls and internal operations with distributed tracing spans. Propagates W3C trace-context headers and exports spans to Jaeger or OTLP.',
+})
+export class TracingService extends A_Component {}
+
+// ─── Configuration Fragments ─────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Carries application-wide configuration: server port, environment name, log level, feature flags, and third-party API base URLs. Loaded once at startup.',
+})
+export class ConfigFragment extends A_Fragment {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Carries database connection parameters: host, port, database name, user, password, pool size, and query timeout. Provided to DatabaseService at startup.',
+})
+export class DatabaseConfigFragment extends A_Fragment {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Carries JWT configuration: secret or public/private key pair, access-token TTL, refresh-token TTL, and issuer/audience claims.',
+})
+export class JwtConfigFragment extends A_Fragment {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Carries cron schedule strings and job-specific tunables such as concurrency limits, retry counts, and execution timeout durations.',
+})
+export class CronConfigFragment extends A_Fragment {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Carries SMTP or provider-API credentials and template IDs for the email service: host, port, sender address, API key, and retry policy.',
+})
+export class EmailConfigFragment extends A_Fragment {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Carries the currently authenticated user identity throughout a request: user ID, email, roles, tenant ID, and token expiry.',
+})
+export class RequestContextFragment extends A_Fragment {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Carries the active database transaction handle and isolation level across a unit-of-work boundary, ensuring multiple repositories share the same transaction.',
+})
+export class TransactionFragment extends A_Fragment {}
+
+// ─── Domain Entities ──────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Domain entity representing a registered user. Has a unique ID, email, hashed password, display name, roles array, created-at timestamp, and soft-delete flag.',
+})
+export class UserEntity extends A_Entity {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Domain entity representing user login credentials stored separately from the profile: provider (local/oauth), provider user ID, hashed secret, and last-used timestamp.',
+})
+export class CredentialsEntity extends A_Entity {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Domain entity representing an active or revoked refresh token: token hash, owner user ID, issued-at, expires-at, device fingerprint, and revocation timestamp.',
+})
+export class RefreshTokenEntity extends A_Entity {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Domain entity representing an uploaded file: unique ID, original name, MIME type, size in bytes, storage bucket key, uploader user ID, and created-at.',
+})
+export class FileEntity extends A_Entity {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Domain entity representing an audit-log entry: ID, actor user ID, action name, target resource type and ID, request metadata, and timestamp.',
+})
+export class AuditLogEntity extends A_Entity {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Domain entity representing a user subscription: ID, user ID, plan name, status (active/cancelled/past-due), billing cycle, next-billing date, and payment-method reference.',
+})
+export class SubscriptionEntity extends A_Entity {}
+
+@A_Frame.Define({
+    namespace: SERVER_APP_NAMESPACE,
+    description: 'Domain entity representing a background job record: ID, type, payload JSON, status (pending/running/done/failed), retry count, and last-run timestamp.',
+})
+export class JobEntity extends A_Entity {}
+
+/**
+ * Components-only array — passed to A_Container as the concept's component list.
+ * Only A_Component subclasses may go here.
+ * Fragments and Entities are registered via @A_Frame.Define globally and are
+ * discovered by A_FrameIndex.listDefinitions() at runtime.
+ */
+export const SERVER_APP_COMPONENTS = [
+    // Infrastructure
+    HttpServer, Router, RequestMiddleware, ResponseMiddleware, ErrorHandler, RateLimiter,
+    // Auth & security
+    AuthService, PermissionService, JwtService, PasswordService, TlsService,
+    // Controllers
+    UserController, AuthController, ResourceController, FileController,
+    HealthController, WebhookController,
+    // Business services
+    UserService, SubscriptionService, EmailService, PushNotificationService,
+    NotificationService, FileStorageService, SearchService, ValidationService,
+    // Data access
+    DatabaseService, UserRepository, ResourceRepository, CacheService, MigrationService,
+    // Events & messaging
+    EventBus, EventConsumer, WebSocketService,
+    // Jobs
+    Cron, CleanupJob, DigestJob, QueueWorker,
+    // Observability
+    Logger, MetricsService, TracingService,
+];

package/jest.config.browser.ts

@@ -18,6 +18,10 @@ const config: Config.InitialOptions = {
         '^.+\\.tsx?$': ['ts-jest', { tsconfig: 'tsconfig.browser.json' }]
     },
     moduleNameMapper: {
+        // Redirect the node env import to the browser env so that the parent
+        // A_FrameChannel class uses the same class reference (injection token)
+        // as A_FrameBrowserChannel, allowing @A_Inject(A_FrameEnv) to resolve.
+        "A-FrameEnv\\.fragment\\.env-node": "<rootDir>/src/lib/A-FrameEnv/A-FrameEnv.fragment.env-browser.ts",
         "@adaas/a-frame/constants/(.*)": "<rootDir>/src/constants/$1",
         "@adaas/a-frame/utils/(.*)": "<rootDir>/src/utils/$1",
         "@adaas/a-frame/helpers/(.*)": "<rootDir>/src/helpers/$1",
@@ -29,10 +33,15 @@ const config: Config.InitialOptions = {
         "@adaas/a-frame/definition": "<rootDir>/src/lib/A-FrameDefinition/index.ts",
         "@adaas/a-frame/dynamic-feature": "<rootDir>/src/lib/A-FrameDynamicFeature/index.ts",
         "@adaas/a-frame/dynamic-structure": "<rootDir>/src/lib/A-FrameDynamicStructure/index.ts",
+        "@adaas/a-frame/dynamic-content": "<rootDir>/src/lib/A-FrameDynamicContent/index.ts",
         "@adaas/a-frame/env": "<rootDir>/src/lib/A-FrameEnv/index.browser.ts",
         "@adaas/a-frame/index": "<rootDir>/src/lib/A-FrameIndex/index.browser.ts",
         "@adaas/a-frame/logger": "<rootDir>/src/lib/A-FrameLogger/index.browser.ts",
+        "@adaas/a-frame/completion": "<rootDir>/src/lib/A-FrameCompletion/index.ts",
+        "@adaas/a-frame/segment": "<rootDir>/src/lib/A-FrameSegment/index.ts",
         "@adaas/a-frame/namespace": "<rootDir>/src/lib/A-FrameNamespace/index.ts",
+        "@adaas/a-frame/models": "<rootDir>/src/lib/A-FrameModels/index.ts",
+        "@adaas/a-frame/schema": "<rootDir>/src/lib/A-FrameSchema/index.ts",
         "@adaas/a-frame/storage": "<rootDir>/src/lib/A-FrameStorage/index.browser.ts",
         "@adaas/a-frame/vector": "<rootDir>/src/lib/A-FrameVector/index.ts",
     }

package/jest.config.examples.ts

@@ -0,0 +1,49 @@
+import type { Config } from '@jest/types';
+
+/**
+ * Jest configuration for runnable examples.
+ *
+ * Unlike the normal test suite (jest.config.ts), this config:
+ *  - Looks in the `examples/` directory instead of `tests/`
+ *  - Matches files named `*.example.ts` so example files are kept
+ *    clearly distinct from unit/integration tests
+ *  - Reuses the same setup file and module aliases as the test suite
+ *
+ * Run with:
+ *   npm run test:examples
+ *   npx jest --config jest.config.examples.ts --no-coverage
+ */
+const config: Config.InitialOptions = {
+    verbose: true,
+    setupFilesAfterEnv: ['<rootDir>/tests/jest.setup.ts'],
+    roots: ['<rootDir>/examples'],
+    testMatch: ['**/*.example.ts'],
+    transform: {
+        '^.+\\.tsx?$': 'ts-jest',
+    },
+    moduleNameMapper: {
+        '@adaas/a-frame/constants/(.*)': '<rootDir>/src/constants/$1',
+        '@adaas/a-frame/utils/(.*)': '<rootDir>/src/utils/$1',
+        '@adaas/a-frame/helpers/(.*)': '<rootDir>/src/helpers/$1',
+        '@adaas/a-frame/types': '<rootDir>/src/types',
+        '@adaas/a-frame/core': '<rootDir>/src/lib/A-Frame/index.ts',
+        '@adaas/a-frame/bundle': '<rootDir>/src/lib/A-FrameBundle/index.ts',
+        '@adaas/a-frame/channel': '<rootDir>/src/lib/A-FrameChannel/index.ts',
+        '@adaas/a-frame/credentials': '<rootDir>/src/lib/A-FrameCredentials/index.ts',
+        '@adaas/a-frame/crypto': '<rootDir>/src/lib/A-FrameCrypto/index.ts',
+        '@adaas/a-frame/definition': '<rootDir>/src/lib/A-FrameDefinition/index.ts',
+        '@adaas/a-frame/dynamic-feature': '<rootDir>/src/lib/A-FrameDynamicFeature/index.ts',
+        '@adaas/a-frame/dynamic-structure': '<rootDir>/src/lib/A-FrameDynamicStructure/index.ts',
+        '@adaas/a-frame/dynamic-content': '<rootDir>/src/lib/A-FrameDynamicContent/index.ts',
+        '@adaas/a-frame/env': '<rootDir>/src/lib/A-FrameEnv/index.ts',
+        '@adaas/a-frame/index': '<rootDir>/src/lib/A-FrameIndex/index.ts',
+        '@adaas/a-frame/logger': '<rootDir>/src/lib/A-FrameLogger/index.ts',
+        '@adaas/a-frame/namespace': '<rootDir>/src/lib/A-FrameNamespace/index.ts',
+        '@adaas/a-frame/completion': '<rootDir>/src/lib/A-FrameCompletion/index.ts',
+        '@adaas/a-frame/segment': '<rootDir>/src/lib/A-FrameSegment/index.ts',
+        '@adaas/a-frame/storage': '<rootDir>/src/lib/A-FrameStorage/index.ts',
+        '@adaas/a-frame/vector': '<rootDir>/src/lib/A-FrameVector/index.ts',
+    },
+};
+
+export default config;

package/jest.config.integration.ts

@@ -0,0 +1,38 @@
+import type { Config } from '@jest/types';
+
+const config: Config.InitialOptions = {
+    verbose: true,
+    setupFilesAfterEnv: ['<rootDir>/tests/jest.setup.ts'],
+    roots: ['<rootDir>/tests/integration'],
+    testPathIgnorePatterns: ['/node_modules/'],
+    transform: {
+        '^.+\\.tsx?$': 'ts-jest'
+    },
+    moduleNameMapper: {
+        "@adaas/a-frame/constants/(.*)": "<rootDir>/src/constants/$1",
+        "@adaas/a-frame/utils/(.*)": "<rootDir>/src/utils/$1",
+        "@adaas/a-frame/helpers/(.*)": "<rootDir>/src/helpers/$1",
+        "@adaas/a-frame/types": "<rootDir>/src/types",
+        "@adaas/a-frame/core": "<rootDir>/src/lib/A-Frame/index.ts",
+        "@adaas/a-frame/bundle": "<rootDir>/src/lib/A-FrameBundle/index.ts",
+        "@adaas/a-frame/channel": "<rootDir>/src/lib/A-FrameChannel/index.ts",
+        "@adaas/a-frame/credentials": "<rootDir>/src/lib/A-FrameCredentials/index.ts",
+        "@adaas/a-frame/crypto": "<rootDir>/src/lib/A-FrameCrypto/index.ts",
+        "@adaas/a-frame/definition": "<rootDir>/src/lib/A-FrameDefinition/index.ts",
+        "@adaas/a-frame/dynamic-feature": "<rootDir>/src/lib/A-FrameDynamicFeature/index.ts",
+        "@adaas/a-frame/dynamic-structure": "<rootDir>/src/lib/A-FrameDynamicStructure/index.ts",
+        "@adaas/a-frame/dynamic-content": "<rootDir>/src/lib/A-FrameDynamicContent/index.ts",
+        "@adaas/a-frame/env": "<rootDir>/src/lib/A-FrameEnv/index.ts",
+        "@adaas/a-frame/index": "<rootDir>/src/lib/A-FrameIndex/index.ts",
+        "@adaas/a-frame/logger": "<rootDir>/src/lib/A-FrameLogger/index.ts",
+        "@adaas/a-frame/namespace": "<rootDir>/src/lib/A-FrameNamespace/index.ts",
+        "@adaas/a-frame/completion": "<rootDir>/src/lib/A-FrameCompletion/index.ts",
+        "@adaas/a-frame/segment": "<rootDir>/src/lib/A-FrameSegment/index.ts",
+        "@adaas/a-frame/storage": "<rootDir>/src/lib/A-FrameStorage/index.ts",
+        "@adaas/a-frame/vector": "<rootDir>/src/lib/A-FrameVector/index.ts",
+        "@adaas/a-frame/models": "<rootDir>/src/lib/A-FrameModels/index.ts",
+        "@adaas/a-frame/schema": "<rootDir>/src/lib/A-FrameSchema/index.ts",
+    }
+};
+
+export default config;

package/jest.config.ts

@@ -1,32 +1,61 @@
 import type { Config } from '@jest/types';
 
-// Sync object
+const moduleNameMapper = {
+    "@adaas/a-frame/constants/(.*)": "<rootDir>/src/constants/$1",
+    "@adaas/a-frame/utils/(.*)": "<rootDir>/src/utils/$1",
+    "@adaas/a-frame/helpers/(.*)": "<rootDir>/src/helpers/$1",
+    "@adaas/a-frame/types": "<rootDir>/src/types",
+    "@adaas/a-frame/core": "<rootDir>/src/lib/A-Frame/index.ts",
+    "@adaas/a-frame/bundle": "<rootDir>/src/lib/A-FrameBundle/index.ts",
+    "@adaas/a-frame/channel": "<rootDir>/src/lib/A-FrameChannel/index.ts",
+    "@adaas/a-frame/credentials": "<rootDir>/src/lib/A-FrameCredentials/index.ts",
+    "@adaas/a-frame/crypto": "<rootDir>/src/lib/A-FrameCrypto/index.ts",
+    "@adaas/a-frame/definition": "<rootDir>/src/lib/A-FrameDefinition/index.ts",
+    "@adaas/a-frame/dynamic-feature": "<rootDir>/src/lib/A-FrameDynamicFeature/index.ts",
+    "@adaas/a-frame/dynamic-structure": "<rootDir>/src/lib/A-FrameDynamicStructure/index.ts",
+    "@adaas/a-frame/dynamic-content": "<rootDir>/src/lib/A-FrameDynamicContent/index.ts",
+    "@adaas/a-frame/env": "<rootDir>/src/lib/A-FrameEnv/index.ts",
+    "@adaas/a-frame/index": "<rootDir>/src/lib/A-FrameIndex/index.ts",
+    "@adaas/a-frame/logger": "<rootDir>/src/lib/A-FrameLogger/index.ts",
+    "@adaas/a-frame/namespace": "<rootDir>/src/lib/A-FrameNamespace/index.ts",
+    "@adaas/a-frame/completion": "<rootDir>/src/lib/A-FrameCompletion/index.ts",
+    "@adaas/a-frame/segment": "<rootDir>/src/lib/A-FrameSegment/index.ts",
+    "@adaas/a-frame/storage": "<rootDir>/src/lib/A-FrameStorage/index.ts",
+    "@adaas/a-frame/vector": "<rootDir>/src/lib/A-FrameVector/index.ts",
+    "@adaas/a-frame/models": "<rootDir>/src/lib/A-FrameModels/index.ts",
+    "@adaas/a-frame/schema": "<rootDir>/src/lib/A-FrameSchema/index.ts",
+};
+
+const transform = { '^.+\\.tsx?$': 'ts-jest' };
+
+/**
+ * Root jest config — runs unit and integration projects with their own setup
+ * files so each project's environment variables and hooks are isolated.
+ *
+ * Unit tests:        npm run test:unit       (no server required)
+ * Integration tests: npm run test:integration (requires a-frame-mcp server)
+ * Both:              npm test
+ */
 const config: Config.InitialOptions = {
     verbose: true,
-    setupFilesAfterEnv: ['<rootDir>/tests/jest.setup.ts'],
-    roots: ['<rootDir>/tests'],
-    testPathIgnorePatterns: ['/node_modules/', '\\.browser\\.test\\.ts$'],
-    transform: {
-        '^.+\\.tsx?$': 'ts-jest'
-    },
-    moduleNameMapper: {
-        "@adaas/a-frame/constants/(.*)": "<rootDir>/src/constants/$1",
-        "@adaas/a-frame/utils/(.*)": "<rootDir>/src/utils/$1",
-        "@adaas/a-frame/helpers/(.*)": "<rootDir>/src/helpers/$1",
-        "@adaas/a-frame/types": "<rootDir>/src/types",
-        "@adaas/a-frame/core": "<rootDir>/src/lib/A-Frame/index.ts",
-        "@adaas/a-frame/bundle": "<rootDir>/src/lib/A-FrameBundle/index.ts",
-        "@adaas/a-frame/channel": "<rootDir>/src/lib/A-FrameChannel/index.ts",
-        "@adaas/a-frame/crypto": "<rootDir>/src/lib/A-FrameCrypto/index.ts",
-        "@adaas/a-frame/definition": "<rootDir>/src/lib/A-FrameDefinition/index.ts",
-        "@adaas/a-frame/dynamic-feature": "<rootDir>/src/lib/A-FrameDynamicFeature/index.ts",
-        "@adaas/a-frame/dynamic-structure": "<rootDir>/src/lib/A-FrameDynamicStructure/index.ts",
-        "@adaas/a-frame/env": "<rootDir>/src/lib/A-FrameEnv/index.ts",
-        "@adaas/a-frame/index": "<rootDir>/src/lib/A-FrameIndex/index.ts",
-        "@adaas/a-frame/logger": "<rootDir>/src/lib/A-FrameLogger/index.ts",
-        "@adaas/a-frame/namespace": "<rootDir>/src/lib/A-FrameNamespace/index.ts",
-        "@adaas/a-frame/storage": "<rootDir>/src/lib/A-FrameStorage/index.ts",
-        "@adaas/a-frame/vector": "<rootDir>/src/lib/A-FrameVector/index.ts",
-    }
+    projects: [
+        {
+            displayName: 'unit',
+            setupFilesAfterEnv: ['<rootDir>/tests/jest.setup.unit.ts'],
+            roots: ['<rootDir>/tests/unit'],
+            testPathIgnorePatterns: ['/node_modules/'],
+            transform,
+            moduleNameMapper,
+        },
+        {
+            displayName: 'integration',
+            setupFilesAfterEnv: ['<rootDir>/tests/jest.setup.ts'],
+            roots: ['<rootDir>/tests/integration'],
+            testPathIgnorePatterns: ['/node_modules/'],
+            transform,
+            moduleNameMapper,
+        },
+    ],
 };
-export default config;
+
+export default config;

package/jest.config.unit.ts

@@ -0,0 +1,38 @@
+import type { Config } from '@jest/types';
+
+const config: Config.InitialOptions = {
+    verbose: true,
+    setupFilesAfterEnv: ['<rootDir>/tests/jest.setup.unit.ts'],
+    roots: ['<rootDir>/tests/unit'],
+    testPathIgnorePatterns: ['/node_modules/'],
+    transform: {
+        '^.+\\.tsx?$': 'ts-jest'
+    },
+    moduleNameMapper: {
+        "@adaas/a-frame/constants/(.*)": "<rootDir>/src/constants/$1",
+        "@adaas/a-frame/utils/(.*)": "<rootDir>/src/utils/$1",
+        "@adaas/a-frame/helpers/(.*)": "<rootDir>/src/helpers/$1",
+        "@adaas/a-frame/types": "<rootDir>/src/types",
+        "@adaas/a-frame/core": "<rootDir>/src/lib/A-Frame/index.ts",
+        "@adaas/a-frame/bundle": "<rootDir>/src/lib/A-FrameBundle/index.ts",
+        "@adaas/a-frame/channel": "<rootDir>/src/lib/A-FrameChannel/index.ts",
+        "@adaas/a-frame/credentials": "<rootDir>/src/lib/A-FrameCredentials/index.ts",
+        "@adaas/a-frame/crypto": "<rootDir>/src/lib/A-FrameCrypto/index.ts",
+        "@adaas/a-frame/definition": "<rootDir>/src/lib/A-FrameDefinition/index.ts",
+        "@adaas/a-frame/dynamic-feature": "<rootDir>/src/lib/A-FrameDynamicFeature/index.ts",
+        "@adaas/a-frame/dynamic-structure": "<rootDir>/src/lib/A-FrameDynamicStructure/index.ts",
+        "@adaas/a-frame/dynamic-content": "<rootDir>/src/lib/A-FrameDynamicContent/index.ts",
+        "@adaas/a-frame/env": "<rootDir>/src/lib/A-FrameEnv/index.ts",
+        "@adaas/a-frame/index": "<rootDir>/src/lib/A-FrameIndex/index.ts",
+        "@adaas/a-frame/logger": "<rootDir>/src/lib/A-FrameLogger/index.ts",
+        "@adaas/a-frame/namespace": "<rootDir>/src/lib/A-FrameNamespace/index.ts",
+        "@adaas/a-frame/completion": "<rootDir>/src/lib/A-FrameCompletion/index.ts",
+        "@adaas/a-frame/segment": "<rootDir>/src/lib/A-FrameSegment/index.ts",
+        "@adaas/a-frame/storage": "<rootDir>/src/lib/A-FrameStorage/index.ts",
+        "@adaas/a-frame/vector": "<rootDir>/src/lib/A-FrameVector/index.ts",
+        "@adaas/a-frame/models": "<rootDir>/src/lib/A-FrameModels/index.ts",
+        "@adaas/a-frame/schema": "<rootDir>/src/lib/A-FrameSchema/index.ts",
+    }
+};
+
+export default config;