@arcadialdev/arcality 2.2.0

package/src/envSetup.ts

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import prompts from 'prompts';
+
+export class UserCancelledError extends Error {
+  constructor(message = 'Usuario canceló la operación') {
+    super(message);
+    this.name = 'UserCancelledError';
+  }
+}
+
+type EnvValues = {
+  BASE_URL?: string;
+  LOGIN_USER?: string;
+  LOGIN_PASSWORD?: string;
+  ARCALITY_PROJECT_ID?: string;
+};
+
+interface ArcalityConfigFile {
+  apiKey?: string;
+  projectId?: string;
+  project?: {
+    name?: string;
+    baseUrl?: string;
+    frameworkDetected?: string;
+  };
+  auth?: {
+    username?: string;
+    password?: string;
+  };
+  runtime?: {
+    yamlOutputDir?: string;
+    reuseSuccessfulYamls?: boolean;
+    singleConfigurationMode?: boolean;
+  };
+}
+
+function envPath(): string {
+  return path.join(process.cwd(), '.env');
+}
+
+function arcalityConfigPath(): string {
+  return path.join(process.cwd(), 'arcality.config');
+}
+
+function escapeEnvValue(v: string): string {
+  const needsQuotes = /[\s"'`\\]/.test(v);
+  const cleaned = v.replace(/"/g, '\\"');
+  return needsQuotes ? `"${cleaned}"` : cleaned;
+}
+
+function parseDotEnv(content: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const idx = trimmed.indexOf('=');
+    if (idx === -1) continue;
+
+    const k = trimmed.slice(0, idx).trim();
+    let v = trimmed.slice(idx + 1).trim();
+
+    if (
+      (v.startsWith('"') && v.endsWith('"')) ||
+      (v.startsWith("'") && v.endsWith("'"))
+    ) {
+      v = v.slice(1, -1);
+    }
+    out[k] = v;
+  }
+  return out;
+}
+
+export function readExistingEnv(): Record<string, string> {
+  const p = envPath();
+  if (!fs.existsSync(p)) return {};
+  return parseDotEnv(fs.readFileSync(p, 'utf8'));
+}
+
+/**
+ * Loads arcality.config if it exists.
+ */
+function loadArcalityConfig(): ArcalityConfigFile | null {
+  const p = arcalityConfigPath();
+  try {
+    if (!fs.existsSync(p)) return null;
+    let raw = fs.readFileSync(p, 'utf8');
+    if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function writeEnv(values: EnvValues): void {
+  const existing = readExistingEnv();
+  const merged = { ...existing, ...values };
+
+  const lines = [
+    '# Auto-generado por Arcality testRunner',
+    `BASE_URL=${escapeEnvValue(merged.BASE_URL ?? '')}`,
+    `LOGIN_USER=${escapeEnvValue(merged.LOGIN_USER ?? '')}`,
+    `LOGIN_PASSWORD=${escapeEnvValue(merged.LOGIN_PASSWORD ?? '')}`,
+  ];
+
+  if (merged.ARCALITY_PROJECT_ID) {
+    lines.push(`ARCALITY_PROJECT_ID=${escapeEnvValue(merged.ARCALITY_PROJECT_ID)}`);
+  }
+  lines.push('');
+
+  fs.writeFileSync(envPath(), lines.join('\n'), 'utf8');
+}
+
+function isValidBaseUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensures environment is configured for test execution.
+ * In single-config mode, reads from arcality.config first.
+ * Falls back to .env prompts for backward compatibility.
+ */
+export async function ensureEnvInteractive(): Promise<void> {
+  // Try to load arcality.config first
+  const arcalityConfig = loadArcalityConfig();
+
+  if (arcalityConfig) {
+    // Inject config values into process.env for the current session
+    if (arcalityConfig.project?.baseUrl) {
+      process.env.BASE_URL = arcalityConfig.project.baseUrl;
+    }
+    if (arcalityConfig.auth?.username) {
+      process.env.LOGIN_USER = arcalityConfig.auth.username;
+    }
+    if (arcalityConfig.auth?.password) {
+      process.env.LOGIN_PASSWORD = arcalityConfig.auth.password;
+    }
+    if (arcalityConfig.projectId) {
+      process.env.ARCALITY_PROJECT_ID = arcalityConfig.projectId;
+    }
+    if (arcalityConfig.apiKey) {
+      process.env.ARCALITY_API_KEY = arcalityConfig.apiKey;
+    }
+
+    // All good — no prompts needed
+    return;
+  }
+
+  // Fallback: prompt for missing .env values (legacy mode)
+  const existing = readExistingEnv();
+  const questions: prompts.PromptObject[] = [];
+
+  if (!existing.BASE_URL) {
+    questions.push({
+      type: 'text',
+      name: 'BASE_URL',
+      message: 'Base URL (ej: http://localhost:3000):',
+      initial: 'http://localhost:3000',
+      validate: (v: string) =>
+        isValidBaseUrl(v) ? true : 'URL inválida (usa http/https)',
+    });
+  }
+
+  if (!existing.LOGIN_USER) {
+    questions.push({
+      type: 'text',
+      name: 'LOGIN_USER',
+      message: 'Usuario:',
+      validate: (v: string) =>
+        v?.trim().length ? true : 'Usuario requerido',
+    });
+  }
+
+  if (!existing.LOGIN_PASSWORD) {
+    questions.push({
+      type: 'password',
+      name: 'LOGIN_PASSWORD',
+      message: 'Contraseña:',
+      validate: (v: string) =>
+        v?.length ? true : 'Contraseña requerida',
+    });
+  }
+
+  if (questions.length > 0) {
+    const res = await prompts(questions, {
+      onCancel: () => {
+        throw new UserCancelledError();
+      },
+    });
+
+    const merged: EnvValues = {
+      BASE_URL: res.BASE_URL ?? existing.BASE_URL,
+      LOGIN_USER: res.LOGIN_USER ?? existing.LOGIN_USER,
+      LOGIN_PASSWORD: res.LOGIN_PASSWORD ?? existing.LOGIN_PASSWORD,
+    };
+    writeEnv(merged);
+    console.log('Archivo .env actualizado.');
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+import 'dotenv/config';
+import { showBanner } from './consoleBanner';
+import { promptAndRunPlaywrightTests } from './testRunner';
+import { KnowledgeService } from './KnowledgeService';
+import { ArcalityClient } from './arcalityClient';
+import { loadConfig } from './configLoader';
+
+async function main() {
+  showBanner();
+
+  const config = loadConfig();
+  const arcalityClient = new ArcalityClient(config.ARCALITY_API_KEY);
+  const knowledgeService = KnowledgeService.getInstance();
+
+  await promptAndRunPlaywrightTests(arcalityClient, knowledgeService);
+}
+
+main().catch((err) => {
+  // Normal user cancellation is not an error
+  if (err instanceof Error && err.name === 'UserCancelledError') {
+    process.exit(130);
+  }
+  console.error(err);
+  process.exit(1);
+});

package/src/projectInspector.ts

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface ProjectContext {
+    name: string;
+    version: string;
+    framework: 'next' | 'vite' | 'cra' | 'unknown';
+    scripts: string[];
+    dependencies: string[];
+}
+
+export function getProjectContext(projectRoot: string): ProjectContext {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    const context: ProjectContext = {
+        name: 'Arcality Project',
+        version: '1.0.0',
+        framework: 'unknown',
+        scripts: [],
+        dependencies: []
+    };
+
+    if (!fs.existsSync(pkgPath)) return context;
+
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        context.name = pkg.name || context.name;
+        context.version = pkg.version || context.version;
+
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        context.dependencies = Object.keys(deps);
+        context.scripts = pkg.scripts ? Object.keys(pkg.scripts) : [];
+
+        if (deps['next']) context.framework = 'next';
+        else if (deps['vite']) context.framework = 'vite';
+        else if (deps['react-scripts']) context.framework = 'cra';
+
+    } catch (e) {
+        // Ignorar errores de lectura
+    }
+
+    return context;
+}

package/src/services/collectiveMemoryService.ts

@@ -0,0 +1,178 @@
+/**
+ * collectiveMemoryService.ts
+ * Servicio de escritura hacia la Memoria Colectiva del backend de Arcality.
+ *
+ * REGLAS CRÍTICAS:
+ * - NUNCA interrumpe el flujo principal (todo en try/catch silencioso)
+ * - NUNCA envía datos sensibles (passwords, tokens, PII)
+ * - NUNCA duplica fields (valida contra /portal/context primero)
+ * - SIEMPRE usa snake_case según JsonNamingPolicy.SnakeCaseLower del servidor
+ * - NUNCA envía project_id vacío o con GUID cero
+ */
+
+const getBase = () => process.env.ARCALITY_API_URL ? `${process.env.ARCALITY_API_URL}/api/v1` : null;
+const getKey  = () => process.env.ARCALITY_API_KEY || '';
+const getPid  = () => process.env.ARCALITY_PROJECT_ID || '';
+
+const EMPTY_GUID = '00000000-0000-0000-0000-000000000000';
+
+function isConfigured(): boolean {
+    const base = getBase();
+    const key  = getKey();
+    const pid  = getPid();
+
+    if (!base || !key || !pid || pid === EMPTY_GUID) {
+        // Silencioso — no loguear en cada percepción para no hacer ruido
+        return false;
+    }
+    return true;
+}
+
+// ─── 1. REGLAS DE UI / NEGOCIO ──────────────────────────────────────────────
+
+export type RuleType = 'UI_UX' | 'VALIDATION' | 'NAVIGATION' | 'BUSINESS';
+export type Severity = 'critical' | 'important' | 'suggestion';
+
+export async function pushRule(rule: {
+    rule_type: RuleType;
+    title: string;
+    description: string;
+    severity?: Severity;
+}): Promise<string | null> {
+    if (!isConfigured()) return null;
+    try {
+        const res = await fetch(`${getBase()}/portal/rules`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': getKey()
+            },
+            body: JSON.stringify({
+                project_id: getPid(),
+                rule_type: rule.rule_type,
+                title: rule.title.substring(0, 100),
+                description: rule.description.substring(0, 500),
+                severity: rule.severity ?? 'important',
+                source: 'agent'
+            })
+        });
+
+        if (!res.ok) {
+            console.warn(`[CollectiveMemory] pushRule HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+            return null;
+        }
+
+        const data = await res.json();
+        console.log(`\x1b[32m[CollectiveMemory] ✅ Regla guardada: "${rule.title}"\x1b[0m`);
+        return data.id ?? null;
+    } catch (err: any) {
+        console.warn(`[CollectiveMemory] pushRule error: ${err?.message}`);
+        return null;
+    }
+}
+
+// ─── 2. CATÁLOGO DE CAMPOS ──────────────────────────────────────────────────
+
+export type FieldType = 'email' | 'password' | 'text' | 'number' | 'select' | 'checkbox' | 'textarea' | 'date';
+
+export async function pushField(field: {
+    field_identifier: string;
+    field_type?: FieldType | string;
+    is_required?: boolean;
+    validation_rule?: string;
+    page_id?: string | null;
+    existingFieldIds?: string[]; // Lista de ids ya guardados para deduplicación
+}): Promise<string | null> {
+    if (!isConfigured()) return null;
+
+    // Deduplicación: no insertar si ya existe en el contexto recuperado
+    if (field.existingFieldIds?.includes(field.field_identifier)) {
+        return null; // Ya catalogado, no duplicar
+    }
+
+    try {
+        const res = await fetch(`${getBase()}/portal/fields`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': getKey()
+            },
+            body: JSON.stringify({
+                project_id: getPid(),
+                page_id: field.page_id ?? null,
+                field_identifier: field.field_identifier.substring(0, 100),
+                field_type: field.field_type ?? 'text',
+                is_required: field.is_required ?? false,
+                validation_rule: field.validation_rule?.substring(0, 300) ?? null,
+                source: 'agent'
+            })
+        });
+
+        if (!res.ok) {
+            return null;
+        }
+
+        const data = await res.json();
+        return data.id ?? null;
+    } catch (err: any) {
+        // Silencioso — fire-and-forget, 'terminated' es esperado al finalizar el proceso
+        return null;
+    }
+}
+
+// ─── 3. CONOCIMIENTO / DOCUMENTACIÓN ────────────────────────────────────────
+
+export type DocType = 'PROCESS' | 'VALIDATION' | 'NAVIGATION' | 'COMPONENT' | 'GENERAL';
+
+export async function pushKnowledge(knowledge: {
+    doc_type: DocType;
+    title: string;
+    content: string;
+}): Promise<string | null> {
+    if (!isConfigured()) return null;
+    try {
+        const res = await fetch(`${getBase()}/portal/knowledge`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': getKey()
+            },
+            body: JSON.stringify({
+                project_id: getPid(),
+                doc_type: knowledge.doc_type,
+                title: knowledge.title.substring(0, 150),
+                content: knowledge.content.substring(0, 500),
+                source: 'agent'
+            })
+        });
+
+        if (!res.ok) {
+            console.warn(`[CollectiveMemory] pushKnowledge HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+            return null;
+        }
+
+        const data = await res.json();
+        console.log(`\x1b[32m[CollectiveMemory] ✅ Conocimiento guardado: "${knowledge.title}"\x1b[0m`);
+        return data.id ?? null;
+    } catch (err: any) {
+        console.warn(`[CollectiveMemory] pushKnowledge error: ${err?.message}`);
+        return null;
+    }
+}
+
+// ─── HELPER: Obtener campos ya conocidos para deduplicación ─────────────────
+
+export async function getKnownFieldIdentifiers(pathUrl: string): Promise<string[]> {
+    if (!isConfigured()) return [];
+    try {
+        const res = await fetch(
+            `${getBase()}/portal/context?project_id=${getPid()}&path=${encodeURIComponent(pathUrl)}`,
+            { headers: { 'x-api-key': getKey() } }
+        );
+        if (!res.ok) return [];
+        const data = await res.json();
+        return (data?.fields ?? []).map((f: any) => f.field_identifier ?? '').filter(Boolean);
+    } catch {
+        return [];
+    }
+}

package/src/testRunner.ts

@@ -0,0 +1,201 @@
+import 'dotenv/config';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { select, isCancel, outro, spinner, text } from '@clack/prompts';
+import chalk from 'chalk';
+import { ensureEnvInteractive, readExistingEnv } from './envSetup';
+import { KnowledgeService } from './KnowledgeService';
+import { ArcalityClient } from './arcalityClient';
+
+type Choice = { title: string; value: string };
+
+class UserCancelledError extends Error {
+    constructor(message = 'User cancelled the operation') {
+        super(message);
+        this.name = 'UserCancelledError';
+    }
+}
+
+function walk(dir: string): string[] {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const files: string[] = [];
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) files.push(...walk(full));
+        else files.push(full);
+    }
+    return files;
+}
+
+function isPlaywrightTestFile(file: string): boolean {
+    return (
+        file.endsWith('.spec.ts') ||
+        file.endsWith('.spec.js') ||
+        file.endsWith('.test.ts') ||
+        file.endsWith('.test.js')
+    );
+}
+
+function getChoices(testDir: string): { label: string; value: string }[] {
+    if (!fs.existsSync(testDir)) return [];
+
+    const files = walk(testDir).filter(isPlaywrightTestFile).sort();
+    const rels = files.map((abs) => path.relative(process.cwd(), abs).split(path.sep).join('/'));
+
+    return [
+        ...rels.map((r) => ({ label: r, value: r })),
+        { label: '❌ Exit', value: '__EXIT__' },
+    ];
+}
+
+function ensureInteractiveStdin(): void {
+    // If NO TTY, arrows will not work. Better to fail with a clear message.
+    if (!process.stdin.isTTY) {
+        throw new Error(
+            'The terminal is not interactive (stdin is not TTY). Run this command in a real terminal (not a pipe), and avoid ts-node-dev/watch.'
+        );
+    }
+}
+
+async function runPlaywright(selection: string): Promise<void> {
+    const isWin = process.platform === 'win32';
+    const pwBin = isWin
+        ? path.join(process.cwd(), 'node_modules', '.bin', 'playwright.cmd')
+        : path.join(process.cwd(), 'node_modules', '.bin', 'playwright');
+
+    const baseArgs = ['test', '--headed', '--project=chromium'];
+    const args =
+        selection === '__ALL__'
+            ? baseArgs
+            : [...baseArgs, selection];
+
+    const s = spinner();
+    s.start(`Running test: ${selection}`);
+
+    let triedNpx = false;
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let bin = pwBin;
+        let binArgs = args;
+        let useShell = isWin;
+        if (triedNpx) {
+            bin = isWin ? 'npx.cmd' : 'npx';
+            binArgs = ['playwright', ...args];
+            useShell = isWin;
+        }
+
+        const spawnBin = (isWin && bin.includes(' ')) ? `"${bin}"` : bin;
+
+        try {
+            await new Promise<void>((resolve, reject) => {
+                const child = spawn(spawnBin, binArgs, {
+                    stdio: 'inherit',
+                    shell: useShell,
+                    windowsHide: true,
+                    env: process.env,
+                    cwd: process.cwd(),
+                });
+                process.removeAllListeners('SIGINT');
+                const onSigint = () => {
+                    child.kill('SIGINT');
+                    reject(new UserCancelledError());
+                };
+                process.once('SIGINT', onSigint);
+                child.on('close', (code: any) => {
+                    process.removeListener('SIGINT', onSigint);
+                    if (code === 0) resolve();
+                    else reject(new Error(`Arcality engine finished with code ${code}`));
+                });
+                child.on('error', (err: any) => {
+                    process.removeListener('SIGINT', onSigint);
+                    reject(err);
+                });
+            });
+
+            s.message('Performing report rebranding...');
+            try {
+                const isWin = process.platform === 'win32';
+                const nodeCmd = isWin ? 'node.exe' : 'node';
+                const { spawnSync } = require('node:child_process');
+                spawnSync(nodeCmd, [path.join(process.cwd(), 'scripts', 'rebrand-report.mjs')], { stdio: 'ignore', windowsHide: true });
+            } catch (e) { /* ignore */ }
+
+            s.stop(chalk.green('✅ Test completed.'));
+
+            const reportPath = path.join(process.cwd(), 'tests-report', 'index.html');
+            if (fs.existsSync(reportPath)) {
+                if (isWin) {
+                    spawn('cmd', ['/c', 'start', '""', `"${reportPath}"`], {
+                        stdio: 'ignore',
+                        shell: true,
+                        detached: true,
+                        windowsHide: true
+                    });
+                } else {
+                    const openCmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+                    spawn(openCmd, [reportPath], {
+                        stdio: 'ignore',
+                        shell: true,
+                        detached: true
+                    });
+                }
+            }
+            return;
+        } catch (err) {
+            lastError = err;
+            if (!triedNpx) {
+                triedNpx = true;
+                continue;
+            }
+            s.stop(chalk.red('❌ The test failed.'));
+            if (err instanceof Error) {
+                throw new Error(`Arcality Engine Error:\n${err.message}`);
+            } else {
+                throw err;
+            }
+        }
+    }
+    throw lastError;
+}
+
+export async function promptAndRunPlaywrightTests(arcalityClient: ArcalityClient, knowledgeService: KnowledgeService): Promise<void> {
+    while (true) {
+        try {
+            await ensureEnvInteractive();
+
+            const testDir = path.join(process.cwd(), 'tests');
+            const options = getChoices(testDir);
+
+            if (options.length === 0) {
+                console.log('No tests found in:', testDir);
+                return;
+            }
+
+            const selection = await select({
+                message: 'Select the test to run:',
+                options,
+            });
+
+            if (isCancel(selection) || selection === '__EXIT__') {
+                outro(chalk.cyan('See you later!'));
+                return;
+            }
+
+            await runPlaywright(selection as string);
+
+            await text({
+                message: 'Press Enter to return to menu...',
+                placeholder: 'Enter'
+            });
+
+        } catch (err) {
+            if (err instanceof UserCancelledError) {
+                outro(chalk.cyan('Operation cancelled.'));
+                return;
+            }
+            console.error('Error:', err instanceof Error ? err.message : err);
+            await new Promise(res => setTimeout(res, 1000));
+        }
+    }
+}