@arcadialdev/arcality 2.2.0

package/.agents/skills/nodejs-backend-patterns/references/advanced-patterns.md

@@ -0,0 +1,430 @@
+# Node.js Advanced Patterns
+
+Advanced patterns for dependency injection, database integration, authentication, caching, and API response formatting.
+
+## Dependency Injection
+
+### DI Container
+
+```typescript
+// di-container.ts
+import { Pool } from "pg";
+import { UserRepository } from "./repositories/user.repository";
+import { UserService } from "./services/user.service";
+import { UserController } from "./controllers/user.controller";
+import { AuthService } from "./services/auth.service";
+
+class Container {
+  private instances = new Map<string, any>();
+
+  register<T>(key: string, factory: () => T): void {
+    this.instances.set(key, factory);
+  }
+
+  resolve<T>(key: string): T {
+    const factory = this.instances.get(key);
+    if (!factory) {
+      throw new Error(`No factory registered for ${key}`);
+    }
+    return factory();
+  }
+
+  singleton<T>(key: string, factory: () => T): void {
+    let instance: T;
+    this.instances.set(key, () => {
+      if (!instance) {
+        instance = factory();
+      }
+      return instance;
+    });
+  }
+}
+
+export const container = new Container();
+
+// Register dependencies
+container.singleton(
+  "db",
+  () =>
+    new Pool({
+      host: process.env.DB_HOST,
+      port: parseInt(process.env.DB_PORT || "5432"),
+      database: process.env.DB_NAME,
+      user: process.env.DB_USER,
+      password: process.env.DB_PASSWORD,
+      max: 20,
+      idleTimeoutMillis: 30000,
+      connectionTimeoutMillis: 2000,
+    }),
+);
+
+container.singleton(
+  "userRepository",
+  () => new UserRepository(container.resolve("db")),
+);
+
+container.singleton(
+  "userService",
+  () => new UserService(container.resolve("userRepository")),
+);
+
+container.register(
+  "userController",
+  () => new UserController(container.resolve("userService")),
+);
+
+container.singleton(
+  "authService",
+  () => new AuthService(container.resolve("userRepository")),
+);
+```
+
+## Database Patterns
+
+### PostgreSQL with Connection Pool
+
+```typescript
+// config/database.ts
+import { Pool, PoolConfig } from "pg";
+
+const poolConfig: PoolConfig = {
+  host: process.env.DB_HOST,
+  port: parseInt(process.env.DB_PORT || "5432"),
+  database: process.env.DB_NAME,
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+};
+
+export const pool = new Pool(poolConfig);
+
+// Test connection
+pool.on("connect", () => {
+  console.log("Database connected");
+});
+
+pool.on("error", (err) => {
+  console.error("Unexpected database error", err);
+  process.exit(-1);
+});
+
+// Graceful shutdown
+export const closeDatabase = async () => {
+  await pool.end();
+  console.log("Database connection closed");
+};
+```
+
+### MongoDB with Mongoose
+
+```typescript
+// config/mongoose.ts
+import mongoose from "mongoose";
+
+const connectDB = async () => {
+  try {
+    await mongoose.connect(process.env.MONGODB_URI!, {
+      maxPoolSize: 10,
+      serverSelectionTimeoutMS: 5000,
+      socketTimeoutMS: 45000,
+    });
+
+    console.log("MongoDB connected");
+  } catch (error) {
+    console.error("MongoDB connection error:", error);
+    process.exit(1);
+  }
+};
+
+mongoose.connection.on("disconnected", () => {
+  console.log("MongoDB disconnected");
+});
+
+mongoose.connection.on("error", (err) => {
+  console.error("MongoDB error:", err);
+});
+
+export { connectDB };
+
+// Model example
+import { Schema, model, Document } from "mongoose";
+
+interface IUser extends Document {
+  name: string;
+  email: string;
+  password: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const userSchema = new Schema<IUser>(
+  {
+    name: { type: String, required: true },
+    email: { type: String, required: true, unique: true },
+    password: { type: String, required: true },
+  },
+  {
+    timestamps: true,
+  },
+);
+
+// Indexes
+userSchema.index({ email: 1 });
+
+export const User = model<IUser>("User", userSchema);
+```
+
+### Transaction Pattern
+
+```typescript
+// services/order.service.ts
+import { Pool } from "pg";
+
+export class OrderService {
+  constructor(private db: Pool) {}
+
+  async createOrder(userId: string, items: any[]) {
+    const client = await this.db.connect();
+
+    try {
+      await client.query("BEGIN");
+
+      // Create order
+      const orderResult = await client.query(
+        "INSERT INTO orders (user_id, total) VALUES ($1, $2) RETURNING id",
+        [userId, calculateTotal(items)],
+      );
+      const orderId = orderResult.rows[0].id;
+
+      // Create order items
+      for (const item of items) {
+        await client.query(
+          "INSERT INTO order_items (order_id, product_id, quantity, price) VALUES ($1, $2, $3, $4)",
+          [orderId, item.productId, item.quantity, item.price],
+        );
+
+        // Update inventory
+        await client.query(
+          "UPDATE products SET stock = stock - $1 WHERE id = $2",
+          [item.quantity, item.productId],
+        );
+      }
+
+      await client.query("COMMIT");
+      return orderId;
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+}
+```
+
+## Authentication & Authorization
+
+### JWT Authentication
+
+```typescript
+// services/auth.service.ts
+import jwt from "jsonwebtoken";
+import bcrypt from "bcrypt";
+import { UserRepository } from "../repositories/user.repository";
+import { UnauthorizedError } from "../utils/errors";
+
+export class AuthService {
+  constructor(private userRepository: UserRepository) {}
+
+  async login(email: string, password: string) {
+    const user = await this.userRepository.findByEmail(email);
+
+    if (!user) {
+      throw new UnauthorizedError("Invalid credentials");
+    }
+
+    const isValid = await bcrypt.compare(password, user.password);
+
+    if (!isValid) {
+      throw new UnauthorizedError("Invalid credentials");
+    }
+
+    const token = this.generateToken({
+      userId: user.id,
+      email: user.email,
+    });
+
+    const refreshToken = this.generateRefreshToken({
+      userId: user.id,
+    });
+
+    return {
+      token,
+      refreshToken,
+      user: {
+        id: user.id,
+        name: user.name,
+        email: user.email,
+      },
+    };
+  }
+
+  async refreshToken(refreshToken: string) {
+    try {
+      const payload = jwt.verify(
+        refreshToken,
+        process.env.REFRESH_TOKEN_SECRET!,
+      ) as { userId: string };
+
+      const user = await this.userRepository.findById(payload.userId);
+
+      if (!user) {
+        throw new UnauthorizedError("User not found");
+      }
+
+      const token = this.generateToken({
+        userId: user.id,
+        email: user.email,
+      });
+
+      return { token };
+    } catch (error) {
+      throw new UnauthorizedError("Invalid refresh token");
+    }
+  }
+
+  private generateToken(payload: any): string {
+    return jwt.sign(payload, process.env.JWT_SECRET!, {
+      expiresIn: "15m",
+    });
+  }
+
+  private generateRefreshToken(payload: any): string {
+    return jwt.sign(payload, process.env.REFRESH_TOKEN_SECRET!, {
+      expiresIn: "7d",
+    });
+  }
+}
+```
+
+## Caching Strategies
+
+```typescript
+// utils/cache.ts
+import Redis from "ioredis";
+
+const redis = new Redis({
+  host: process.env.REDIS_HOST,
+  port: parseInt(process.env.REDIS_PORT || "6379"),
+  retryStrategy: (times) => {
+    const delay = Math.min(times * 50, 2000);
+    return delay;
+  },
+});
+
+export class CacheService {
+  async get<T>(key: string): Promise<T | null> {
+    const data = await redis.get(key);
+    return data ? JSON.parse(data) : null;
+  }
+
+  async set(key: string, value: any, ttl?: number): Promise<void> {
+    const serialized = JSON.stringify(value);
+    if (ttl) {
+      await redis.setex(key, ttl, serialized);
+    } else {
+      await redis.set(key, serialized);
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await redis.del(key);
+  }
+
+  async invalidatePattern(pattern: string): Promise<void> {
+    const keys = await redis.keys(pattern);
+    if (keys.length > 0) {
+      await redis.del(...keys);
+    }
+  }
+}
+
+// Cache decorator
+export function Cacheable(ttl: number = 300) {
+  return function (
+    target: any,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = async function (...args: any[]) {
+      const cache = new CacheService();
+      const cacheKey = `${propertyKey}:${JSON.stringify(args)}`;
+
+      const cached = await cache.get(cacheKey);
+      if (cached) {
+        return cached;
+      }
+
+      const result = await originalMethod.apply(this, args);
+      await cache.set(cacheKey, result, ttl);
+
+      return result;
+    };
+
+    return descriptor;
+  };
+}
+```
+
+## API Response Format
+
+```typescript
+// utils/response.ts
+import { Response } from "express";
+
+export class ApiResponse {
+  static success<T>(
+    res: Response,
+    data: T,
+    message?: string,
+    statusCode = 200,
+  ) {
+    return res.status(statusCode).json({
+      status: "success",
+      message,
+      data,
+    });
+  }
+
+  static error(res: Response, message: string, statusCode = 500, errors?: any) {
+    return res.status(statusCode).json({
+      status: "error",
+      message,
+      ...(errors && { errors }),
+    });
+  }
+
+  static paginated<T>(
+    res: Response,
+    data: T[],
+    page: number,
+    limit: number,
+    total: number,
+  ) {
+    return res.json({
+      status: "success",
+      data,
+      pagination: {
+        page,
+        limit,
+        total,
+        pages: Math.ceil(total / limit),
+      },
+    });
+  }
+}
+```

package/.agents/skills/playwright-best-practices/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright © 2026 Currents Software Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/.agents/skills/playwright-best-practices/README.md

@@ -0,0 +1,147 @@
+```
+
+░█▀█░█░░░█▀█░█░█░█░█░█▀▄░▀█▀░█▀▀░█░█░▀█▀░░░█▀▄░█▀▀░█▀▀░▀█▀░░░█▀█░█▀▄░█▀█░█▀▀░▀█▀░▀█▀░█▀▀░█▀▀░█▀▀░
+░█▀▀░█░░░█▀█░░█░░█▄█░█▀▄░░█░░█░█░█▀█░░█░░░░█▀▄░█▀▀░▀▀█░░█░░░░█▀▀░█▀▄░█▀█░█░░░░█░░░█░░█░░░█▀▀░▀▀█░
+░▀░░░▀▀▀░▀░▀░░▀░░▀░▀░▀░▀░▀▀▀░▀▀▀░▀░▀░░▀░░░░▀▀░░▀▀▀░▀▀▀░░▀░░░░▀░░░▀░▀░▀░▀░▀▀▀░░▀░░▀▀▀░▀▀▀░▀▀▀░▀▀▀░
+```
+<img src="https://currents.dev/favicon-96x96.png" width="24" height="24" align="left" />by [currents.dev](https://currents.dev?utm_source=ai-skill) - The all-in-one Dashboard for Playwright Testing.
+
+# Playwright Best Practices Skill
+
+A skill that gives the AI specialized guidance for writing, debugging, and maintaining **Playwright** tests in **TypeScript**. Use it in any repo where you work with Playwright so the assistant follows best practices for E2E, component, API, visual regression, accessibility, security, i18n, Electron, and browser extension testing.
+
+## Installation
+
+```bash
+npx skills add https://github.com/currents-dev/playwright-best-practices-skill
+```
+
+The skill is activity-based: the AI is directed to the right reference depending on what you're doing, so you get focused advice without loading everything at once.
+
+## When the Skill Is Used
+
+The skill triggers when the AI infers you need help with things like:
+
+- Writing new E2E, component, API, visual regression, or accessibility tests
+- Testing mobile/responsive layouts, touch gestures, or device emulation
+- Implementing file uploads/downloads, date/time mocking, or WebSocket testing
+- Handling OAuth popups, geolocation, permissions, or multi-tab flows
+- Testing iframes, canvas/WebGL, service workers, or PWA features
+- Testing Electron desktop apps or browser extensions
+- Internationalization (i18n), locales, RTL layouts, or date/number formats
+- Testing error states, offline mode, or network failure scenarios
+- Security testing (XSS, CSRF, authentication, authorization)
+- Performance testing with Web Vitals or Lighthouse
+- Reviewing or refactoring Playwright test code
+- Fixing flaky tests or debugging failures
+- Setting up CI/CD, test coverage, or global setup/teardown
+- Configuring projects, dependencies, parallel runs, or sharding
+
+You don't have to mention "skill" or "Playwright best practices"; describe your task (e.g. "fix this flaky login test" or "add accessibility tests") and the AI will use the skill when it's relevant.
+
+## What's Inside
+
+**57 reference documents** organized into 8 categories:
+
+### Core (`core/`)
+
+| Topic                | Reference                   | Use for                                          |
+| -------------------- | --------------------------- | ------------------------------------------------ |
+| Test structure       | `test-suite-structure.md`   | Structure, config, E2E/component/API/visual tests |
+| Locators             | `locators.md`               | Selectors, robustness, avoiding brittle locators |
+| Assertions & waiting | `assertions-waiting.md`     | Expect APIs, auto-waiting, polling               |
+| Page Object Model    | `page-object-model.md`      | POM structure and patterns                       |
+| Fixtures & hooks     | `fixtures-hooks.md`         | Setup, teardown, auth, custom fixtures           |
+| Test data            | `test-data.md`              | Factories, Faker, data-driven testing            |
+| Annotations          | `annotations.md`            | skip, fixme, slow, test steps                    |
+| Configuration        | `configuration.md`          | playwright.config.ts options                     |
+| Global setup         | `global-setup.md`           | globalSetup/Teardown, DB migrations              |
+| Projects             | `projects-dependencies.md`  | Project config, dependencies, filtering          |
+
+### Debugging (`debugging/`)
+
+| Topic          | Reference            | Use for                                    |
+| -------------- | -------------------- | ------------------------------------------ |
+| Debugging      | `debugging.md`       | Trace viewer, inspector, common issues     |
+| Flaky tests    | `flaky-tests.md`     | Detection, diagnosis, fixing, quarantine   |
+| Error testing  | `error-testing.md`   | Error boundaries, offline, network failures |
+| Console errors | `console-errors.md`  | Capturing and failing on JS errors         |
+
+### Testing Patterns (`testing-patterns/`)
+
+| Topic               | Reference                 | Use for                                        |
+| ------------------- | ------------------------- | ---------------------------------------------- |
+| Accessibility       | `accessibility.md`        | Axe-core, keyboard nav, ARIA, focus management |
+| API testing         | `api-testing.md`          | REST API testing, request context              |
+| Component testing   | `component-testing.md`    | CT setup, mounting, props, mocking             |
+| Visual regression   | `visual-regression.md`    | Screenshot comparison, thresholds              |
+| File operations     | `file-operations.md`      | Upload, download basics                        |
+| File upload/download| `file-upload-download.md` | Progress, cancellation, retry patterns         |
+| Forms validation    | `forms-validation.md`     | Form testing, validation states                |
+| Drag and drop       | `drag-drop.md`            | Drag-and-drop interactions                     |
+| GraphQL testing     | `graphql-testing.md`      | GraphQL queries, mutations, mocking            |
+| Canvas/WebGL        | `canvas-webgl.md`         | Canvas testing, charts, WebGL, games           |
+| i18n                | `i18n.md`                 | Locales, RTL, date/number formats              |
+| Electron            | `electron.md`             | Desktop apps, IPC, main/renderer process       |
+| Browser extensions  | `browser-extensions.md`   | Popup, background, content scripts, APIs       |
+| Security testing    | `security-testing.md`     | XSS, CSRF, auth security, authorization        |
+| Performance testing | `performance-testing.md`  | Web Vitals, budgets, Lighthouse                |
+
+### Advanced (`advanced/`)
+
+| Topic            | Reference               | Use for                                     |
+| ---------------- | ----------------------- | ------------------------------------------- |
+| Authentication   | `authentication.md`     | Login flows, session storage, cookies       |
+| Auth flows       | `authentication-flows.md` | MFA, password reset, complex auth         |
+| Mobile testing   | `mobile-testing.md`     | Device emulation, touch gestures, viewports |
+| Clock mocking    | `clock-mocking.md`      | Date/time mocking, timezones, timers        |
+| Multi-context    | `multi-context.md`      | Popups, new tabs, OAuth flows               |
+| Multi-user       | `multi-user.md`         | Collaboration, RBAC, concurrent actions     |
+| Network advanced | `network-advanced.md`   | GraphQL, HAR, request modification          |
+| Third-party      | `third-party.md`        | OAuth, payments, email/SMS mocking          |
+
+### Browser APIs (`browser-apis/`)
+
+| Topic           | Reference            | Use for                                     |
+| --------------- | -------------------- | ------------------------------------------- |
+| Browser APIs    | `browser-apis.md`    | Geolocation, permissions, clipboard, camera |
+| WebSockets      | `websockets.md`      | Real-time testing, SSE, reconnection        |
+| iFrames         | `iframes.md`         | Cross-origin, nested, dynamic iframes       |
+| Service workers | `service-workers.md` | PWA, caching, offline, push notifications   |
+
+### Architecture (`architecture/`)
+
+| Topic             | Reference              | Use for                              |
+| ----------------- | ---------------------- | ------------------------------------ |
+| POM vs fixtures   | `pom-vs-fixtures.md`   | Choosing between patterns            |
+| Test architecture | `test-architecture.md` | Test type selection, structure       |
+| When to mock      | `when-to-mock.md`      | Mock vs real services decisions      |
+
+### Frameworks (`frameworks/`)
+
+| Topic   | Reference     | Use for                        |
+| ------- | ------------- | ------------------------------ |
+| React   | `react.md`    | React-specific testing patterns |
+| Angular | `angular.md`  | Angular-specific testing        |
+| Vue     | `vue.md`      | Vue/Nuxt testing patterns       |
+| Next.js | `nextjs.md`   | Next.js SSR/SSG testing         |
+
+### Infrastructure & CI/CD (`infrastructure-ci-cd/`)
+
+| Topic            | Reference              | Use for                              |
+| ---------------- | ---------------------- | ------------------------------------ |
+| CI/CD            | `ci-cd.md`             | Pipelines, general CI setup          |
+| GitHub Actions   | `github-actions.md`    | GitHub-specific workflows            |
+| GitLab CI        | `gitlab.md`            | GitLab-specific pipelines            |
+| Other providers  | `other-providers.md`   | CircleCI, Azure DevOps, Jenkins      |
+| Docker           | `docker.md`            | Container setup, Playwright images   |
+| Parallel/sharding| `parallel-sharding.md` | Sharding, parallel execution         |
+| Performance      | `performance.md`       | Parallel runs, optimization          |
+| Reporting        | `reporting.md`         | Test reporters, artifacts            |
+| Test coverage    | `test-coverage.md`     | V8 coverage, reports, thresholds, CI |
+
+The skill's `SKILL.md` maps your current activity to these references so the right content is used in context.
+
+## License
+
+MIT