arckode-framework 1.3.2 → 1.4.0

package/adapters/jwt.ts

@@ -7,12 +7,14 @@ import type { JwtAdapter } from '../kernel/framework'
 
 export const jwtTokenAdapter: JwtAdapter = {
   sign(payload, secret, expiresIn) {
-    // jsonwebtoken's expiresIn accepts ms-compatible strings (e.g. "24h", "30d")
-    // We cast via unknown to satisfy its StringValue/number union
-    return jwt.sign(payload, secret, { expiresIn: expiresIn as unknown as number })
+    return jwt.sign(payload, secret, {
+      algorithm: 'HS256',
+      expiresIn: expiresIn as unknown as number,
+    })
   },
 
   verify(token, secret) {
-    return jwt.verify(token, secret) as Record<string, unknown>
+    // algorithms whitelist previene ataques de algorithm confusion (none, RS256→HS256)
+    return jwt.verify(token, secret, { algorithms: ['HS256'] }) as Record<string, unknown>
   },
 }

package/adapters/mysql.ts

@@ -43,10 +43,12 @@ class MySQLTransactionAdapter implements DbAdapter {
 
 export class MySQLAdapter implements DbAdapter {
   private pool!: mysql.Pool
+  private connected = false
 
   constructor(private config: MySQLConfig) {}
 
   async connect(): Promise<void> {
+    if (this.connected) return
     this.pool = mysql.createPool({
       host: this.config.host,
       port: this.config.port ?? 3306,
@@ -57,9 +59,9 @@ export class MySQLAdapter implements DbAdapter {
       waitForConnections: true,
       queueLimit: 0,
     })
-    // Verificar conexión al arrancar (fail fast)
     const conn = await this.pool.getConnection()
     conn.release()
+    this.connected = true
   }
 
   async query(sql: string, params: unknown[] = []): Promise<unknown[]> {
@@ -93,6 +95,9 @@ export class MySQLAdapter implements DbAdapter {
   }
 
   async close(): Promise<void> {
-    await this.pool.end()
+    if (this.connected) {
+      await this.pool.end()
+      this.connected = false
+    }
   }
 }

package/adapters/postgres.ts

@@ -4,6 +4,13 @@
 import pg, { type Pool as PgPool } from 'pg'
 import type { DbAdapter } from '../kernel/framework'
 
+// @types/pg 8.20+ con moduleResolution:bundler resuelve index.d.mts donde
+// PoolClient pierde los métodos heredados de ClientBase — interfaz mínima local
+interface TxClient {
+  query(sql: string, params?: unknown[]): Promise<{ rows: Record<string, unknown>[]; rowCount: number | null }>
+  release(err?: Error | boolean): void
+}
+
 export interface PostgresConfig {
   connectionString: string
   poolMin?: number
@@ -12,10 +19,12 @@ export interface PostgresConfig {
 
 export class PostgresAdapter implements DbAdapter {
   private pool!: PgPool
+  private connected = false
 
   constructor(private config: PostgresConfig) {}
 
   async connect(): Promise<void> {
+    if (this.connected) return
     this.pool = new pg.Pool({
       connectionString: this.config.connectionString,
       min: this.config.poolMin ?? 2,
@@ -23,6 +32,7 @@ export class PostgresAdapter implements DbAdapter {
     })
     const client = await this.pool.connect()
     client.release()
+    this.connected = true
   }
 
   // Convierte ? a $1, $2, $3... para compatibilidad con PostgreSQL
@@ -46,6 +56,33 @@ export class PostgresAdapter implements DbAdapter {
     }
   }
 
+  async transaction<T>(fn: (adapter: DbAdapter) => Promise<T>): Promise<T> {
+    const client = (await this.pool.connect()) as unknown as TxClient
+    try {
+      await client.query('BEGIN')
+      const txAdapter: DbAdapter = {
+        query: async (sql, params = []) => {
+          const r = await client.query(this.convertPlaceholders(sql), params)
+          return r.rows
+        },
+        run: async (sql, params = []) => {
+          const r = await client.query(this.convertPlaceholders(sql), params)
+          const row = r.rows[0]
+          return { changes: r.rowCount ?? 0, lastId: row?.id != null ? String(row.id) : undefined }
+        },
+        close: async () => {},
+      }
+      const result = await fn(txAdapter)
+      await client.query('COMMIT')
+      return result
+    } catch (err) {
+      await client.query('ROLLBACK')
+      throw err
+    } finally {
+      client.release()
+    }
+  }
+
   async close(): Promise<void> {
     await this.pool.end()
   }

package/adapters/sqlite.ts

@@ -20,16 +20,19 @@ const DEFAULT_CONFIG: SqliteConfig = {
 export class SqliteAdapter implements DbAdapter {
   private db!: Database
   private config: SqliteConfig
+  private connected = false
 
   constructor(config?: Partial<SqliteConfig>) {
     this.config = { ...DEFAULT_CONFIG, ...config }
   }
 
   async connect(): Promise<void> {
+    if (this.connected) return
     this.db = new Database(this.config.path)
 
     if (this.config.wal) this.db.exec('PRAGMA journal_mode = WAL')
     if (this.config.foreignKeys) this.db.exec('PRAGMA foreign_keys = ON')
+    this.connected = true
   }
 
   query(sql: string, params: unknown[] = []): Promise<unknown[]> {
@@ -62,7 +65,10 @@ export class SqliteAdapter implements DbAdapter {
   }
 
   close(): Promise<void> {
-    this.db.close()
+    if (this.connected) {
+      this.db.close()
+      this.connected = false
+    }
     return Promise.resolve()
   }
 }

package/adapters/vendor.d.ts

@@ -0,0 +1,48 @@
+// adapters/vendor.d.ts — Minimal type stubs for optional peer dependencies.
+// pg and redis are optional — users install them only when using those adapters.
+// These stubs let TypeScript compile without the packages installed.
+
+declare module 'pg' {
+  export interface PoolConfig {
+    connectionString?: string
+    min?: number
+    max?: number
+    [key: string]: unknown
+  }
+
+  export interface QueryResult<R = Record<string, unknown>> {
+    rows: R[]
+    rowCount: number | null
+  }
+
+  export interface PoolClient {
+    release(): void
+  }
+
+  export class Pool {
+    constructor(config?: PoolConfig)
+    connect(): Promise<PoolClient>
+    query(sql: string, params?: unknown[]): Promise<QueryResult>
+    end(): Promise<void>
+  }
+
+  const pg: {
+    Pool: typeof Pool
+  } & typeof import('pg')
+  export default pg
+}
+
+declare module 'redis' {
+  export type RedisClientType = {
+    connect(): Promise<void>
+    get(key: string): Promise<string | null>
+    set(key: string, value: string): Promise<unknown>
+    setEx(key: string, seconds: number, value: string): Promise<unknown>
+    del(keys: string | string[]): Promise<unknown>
+    keys(pattern: string): Promise<string[]>
+    flushAll(): Promise<unknown>
+    quit(): Promise<unknown>
+  }
+
+  export function createClient(options?: { url?: string; [key: string]: unknown }): RedisClientType
+}

package/cli/analyze/checks.ts

@@ -0,0 +1,333 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import type { ModuleReport, Violation, Warning } from './types'
+import { fileExists, resolvePath, canonicalizeConnectorName, getAllTsFiles } from './utils'
+
+export type InternalPaths = Map<string, { service: string | null; controller: string | null }>
+
+export async function checkModuleStructure(
+  modulesPath: string,
+  violations: Violation[],
+  warnings: Warning[],
+): Promise<{ modules: ModuleReport[]; internalPaths: InternalPaths }> {
+  const modules: ModuleReport[] = []
+  const internalPaths: InternalPaths = new Map()
+
+  try {
+    const moduleDirs = await readdir(modulesPath, { withFileTypes: true })
+    const moduleNames = moduleDirs.filter(d => d.isDirectory()).map(d => d.name)
+
+    if (moduleNames.length === 0) {
+      warnings.push({ type: 'SINGLE_MODULE', message: 'No hay módulos en src/modules/' })
+    }
+
+    for (const name of moduleNames) {
+      const modPath = join(modulesPath, name)
+      const servicePath = await resolvePath(modPath, ['service.ts', 'actions/service.ts'])
+      const controllerPath = await resolvePath(modPath, ['controller.ts', 'actions/controller.ts'])
+
+      const report: ModuleReport = {
+        name,
+        hasIndex: await fileExists(join(modPath, 'index.ts')),
+        hasService: servicePath !== null,
+        hasController: controllerPath !== null,
+        hasTypes: await fileExists(join(modPath, 'types.ts')),
+        hasSockets: await fileExists(join(modPath, 'sockets.ts')),
+        hasValidators: await fileExists(join(modPath, 'validators', 'schema.ts')),
+        hasTests: await fileExists(join(modPath, 'tests', 'service.test.ts')),
+      }
+
+      internalPaths.set(name, { service: servicePath, controller: controllerPath })
+
+      if (!report.hasIndex) violations.push({ type: 'MISSING_INDEX', module: name, message: `Módulo "${name}" sin index.ts (puerta pública)` })
+      if (!report.hasTypes) violations.push({ type: 'MISSING_TYPES', module: name, message: `Módulo "${name}" sin types.ts (DTOs)` })
+      if (!report.hasSockets) violations.push({ type: 'MISSING_SOCKETS', module: name, message: `Módulo "${name}" sin sockets.ts (hooks opcionales)` })
+      if (!report.hasService) violations.push({ type: 'MISSING_SERVICE', module: name, message: `Módulo "${name}" sin service.ts (al root del módulo)` })
+      if (!report.hasValidators) violations.push({ type: 'MISSING_VALIDATORS', module: name, message: `Módulo "${name}" sin validators/schema.ts` })
+      if (!report.hasTests) violations.push({ type: 'MISSING_TESTS', module: name, message: `Módulo "${name}" sin tests/` })
+
+      modules.push(report)
+    }
+  } catch {
+    violations.push({ type: 'MISSING_INDEX', module: 'modules', message: 'No existe src/modules/' })
+  }
+
+  return { modules, internalPaths }
+}
+
+export async function checkConnectors(
+  connectorsPath: string,
+  crPath: string,
+  modules: ModuleReport[],
+  violations: Violation[],
+  warnings: Warning[],
+): Promise<string[]> {
+  const connectors: string[] = []
+
+  try {
+    const connectorFiles = await readdir(connectorsPath)
+    for (const file of connectorFiles) {
+      if (file.endsWith('.ts')) connectors.push(file)
+    }
+
+    if (connectors.length === 0 && modules.length > 1) {
+      warnings.push({ type: 'NO_CONNECTORS', message: `Hay ${modules.length} módulos pero 0 conectores. Los módulos no están conectados.` })
+    }
+
+    const canonicalMap = new Map<string, string[]>()
+    for (const file of connectors) {
+      const canonical = canonicalizeConnectorName(file)
+      const list = canonicalMap.get(canonical) ?? []
+      list.push(file)
+      canonicalMap.set(canonical, list)
+    }
+    for (const [canonical, files] of canonicalMap) {
+      if (files.length > 1) {
+        violations.push({
+          type: 'DUPLICATE_CONNECTOR',
+          module: 'connectors',
+          message: `Conectores duplicados con mismo nombre lógico "${canonical}": ${files.join(', ')}. Eliminar los stubs muertos del CLI.`,
+        })
+      }
+    }
+
+    try {
+      const crContent = await readFile(crPath, 'utf-8')
+      for (const file of connectors) {
+        const basename = file.replace(/\.ts$/, '')
+        const importPattern = new RegExp(`from\\s+['"][^'"]*connectors\\/${basename}['"]`)
+        if (!importPattern.test(crContent)) {
+          violations.push({
+            type: 'UNREGISTERED_CONNECTOR',
+            module: 'connectors',
+            message: `Conector "${file}" existe pero no se importa en composition-root.ts. Dead code o falta registrar con system.addConnector().`,
+          })
+        }
+      }
+    } catch { /* sin composition-root, ya warned arriba */ }
+  } catch { /* no connectors folder */ }
+
+  if (modules.length > 1 && connectors.length === 0) {
+    violations.push({
+      type: 'MISSING_CONNECTORS',
+      module: 'system',
+      message: `Hay ${modules.length} módulos pero 0 conectores. Los módulos no están conectados. (CLAUDE #5)`,
+    })
+  }
+
+  return connectors
+}
+
+export async function checkCrossImports(
+  modulesPath: string,
+  modules: ModuleReport[],
+  violations: Violation[],
+): Promise<void> {
+  for (const module of modules) {
+    try {
+      const allFiles = await getAllTsFiles(join(modulesPath, module.name))
+      for (const file of allFiles) {
+        const content = await readFile(file, 'utf-8')
+        const relPath = file.replace(modulesPath, '')
+        for (const other of modules) {
+          if (other.name === module.name) continue
+          const importPattern = new RegExp(`from ['"][^'"]*\\/modules\\/${other.name}([/'"]|\$)`)
+          if (importPattern.test(content)) {
+            violations.push({
+              type: 'DIRECT_MODULE_IMPORT',
+              module: module.name,
+              message: `"${relPath}" importa directo de "${other.name}". Usar conector. (CLAUDE #1)`,
+            })
+          }
+        }
+      }
+    } catch { /* no actions dir */ }
+  }
+}
+
+export async function checkConnectorLogic(
+  connectorsPath: string,
+  connectors: string[],
+  violations: Violation[],
+): Promise<void> {
+  const businessPatterns = [
+    /\bif\s*\(/g, /\bswitch\s*\(/g, /\bfor\s*\(/g, /\bwhile\s*\(/g,
+    /\btry\s*\{/g, /\bcatch\s*\(/g, /\bnew\s+\w+Action/g,
+    /\.create\(/g, /\.update\(/g, /\.delete\(/g,
+  ]
+
+  for (const connFile of connectors) {
+    try {
+      const content = await readFile(join(connectorsPath, connFile), 'utf-8')
+      let businessHits = 0
+      for (const pattern of businessPatterns) {
+        const matches = content.match(pattern)
+        if (matches) businessHits += matches.length
+      }
+      if (businessHits > 3) {
+        violations.push({
+          type: 'CONNECTOR_BUSINESS_LOGIC',
+          module: connFile,
+          message: `"${connFile}" tiene ${businessHits} patrones de lógica de negocio. Los conectores solo deben wirear. (CLAUDE #3)`,
+        })
+      }
+    } catch { /* ignore */ }
+  }
+}
+
+export async function checkIndexFiles(
+  modulesPath: string,
+  modules: ModuleReport[],
+  warnings: Warning[],
+): Promise<void> {
+  for (const module of modules) {
+    const indexPath = join(modulesPath, module.name, 'index.ts')
+    try {
+      const content = await readFile(indexPath, 'utf-8')
+      if (content.includes('TODO:') || content.includes('FIXME:')) {
+        warnings.push({
+          type: 'INDEX_PENDING_CHANGES',
+          message: `"${module.name}/index.ts" tiene TODO/FIXME. Revisar antes de continuar.`,
+        })
+      }
+    } catch { /* no index */ }
+  }
+}
+
+export async function checkModuleQuality(
+  modulesPath: string,
+  modules: ModuleReport[],
+  internalPaths: InternalPaths,
+  violations: Violation[],
+  warnings: Warning[],
+): Promise<void> {
+  for (const module of modules) {
+    const modPath = join(modulesPath, module.name)
+    const paths = internalPaths.get(module.name) ?? { service: null, controller: null }
+    const { service: servicePath, controller: controllerPath } = paths
+
+    // Description vacía
+    try {
+      const indexContent = await readFile(join(modPath, 'index.ts'), 'utf-8')
+      if (/description:\s*['"`]\s*['"`]/.test(indexContent)) {
+        violations.push({ type: 'EMPTY_MODULE_DESCRIPTION', module: module.name, message: `"${module.name}" tiene descripción vacía. Todo módulo DEBE documentar su propósito.` })
+      }
+    } catch { /* no index */ }
+
+    // Tests sin casos
+    try {
+      const testContent = await readFile(join(modPath, 'tests', 'service.test.ts'), 'utf-8')
+      if (!/\btest\s*\(|\bit\s*\(|\bdescribe\s*\(/.test(testContent)) {
+        violations.push({ type: 'TESTS_WITHOUT_CASES', module: module.name, message: `"${module.name}/tests/service.test.ts" existe pero no tiene ningún test(). Coverage = 0.` })
+      }
+    } catch { /* no test file */ }
+
+    // Legacy layout warning
+    if ((servicePath?.includes('/actions/')) || (controllerPath?.includes('/actions/'))) {
+      warnings.push({ type: 'LEGACY_ACTIONS_FOLDER', message: `"${module.name}" usa la estructura legacy actions/. Mover service.ts y controller.ts al root del módulo.` })
+    }
+
+    if (controllerPath) {
+      const ctrlContent = await readFile(controllerPath, 'utf-8').catch(() => '')
+
+      // Controller sin validateSchema en rutas mutantes
+      if (/router\.(post|put|patch)\s*\(/.test(ctrlContent) && !/validateSchema\s*\(/.test(ctrlContent)) {
+        violations.push({ type: 'CONTROLLER_MISSING_VALIDATION', module: module.name, message: `"${module.name}/controller.ts" tiene rutas POST/PUT/PATCH sin validateSchema(). Datos no validados llegan al service.` })
+      }
+
+      // ORM directo en controller
+      if (/\borm\.(findMany|findById|create|update|delete|paginate|count)\s*\(/.test(ctrlContent)) {
+        violations.push({ type: 'BUSINESS_LOGIC_IN_CONTROLLER', module: module.name, message: `"${module.name}/controller.ts" llama al ORM directamente. La lógica de datos va en service.ts.` })
+      }
+    }
+
+    if (!servicePath) continue
+
+    const serviceContent = await readFile(servicePath, 'utf-8').catch(() => '')
+
+    // God service
+    const lineCount = serviceContent.split('\n').length
+    if (lineCount > 200) {
+      violations.push({ type: 'GOD_SERVICE', module: module.name, message: `"${module.name}/service.ts" tiene ${lineCount} líneas. Un service > 200 líneas es un God Object — extraer a usecases/.` })
+    }
+
+    // Service cruza módulo
+    for (const other of modules) {
+      if (other.name === module.name) continue
+      if (new RegExp(`from ['"][^'"]*\\/modules\\/${other.name}([/'"]|\$)`).test(serviceContent)) {
+        violations.push({ type: 'SERVICE_IMPORTS_OTHER_MODULE', module: module.name, message: `"${module.name}/service.ts" importa de "${other.name}". Los services no pueden cruzar módulos — usar conector. (CLAUDE #1)` })
+      }
+    }
+
+    // N+1 risk
+    const lines = serviceContent.split('\n')
+    let insideLoop = 0
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i] ?? ''
+      if (/\b(for\s*\(|forEach\s*\(|\.map\s*\(\s*async|\.filter\s*\(\s*async|while\s*\()/.test(line)) insideLoop++
+      const opens = (line.match(/\{/g) ?? []).length
+      const closes = (line.match(/\}/g) ?? []).length
+      if (insideLoop > 0 && closes > opens) insideLoop = Math.max(0, insideLoop - 1)
+      if (insideLoop > 0 && /await\s+\w*orm\w*\.(findMany|findById|create|update|delete|count|paginate)\s*\(/.test(line)) {
+        violations.push({ type: 'N_PLUS_ONE_RISK', module: module.name, message: `"${module.name}/service.ts" línea ${i + 1}: ORM llamado dentro de un loop — riesgo de N+1. Usar findMany/createMany/updateMany fuera del loop.` })
+        break
+      }
+    }
+
+    // IDOR risk — findById sin assertOwnership
+    const filesToScan: string[] = [servicePath]
+    for (const subdir of ['usecases', 'actions']) {
+      try {
+        const subEntries = await readdir(join(modPath, subdir), { withFileTypes: true })
+        for (const e of subEntries) {
+          if (e.isFile() && e.name.endsWith('.ts') && e.name !== 'service.ts' && e.name !== 'controller.ts') {
+            filesToScan.push(join(modPath, subdir, e.name))
+          }
+        }
+      } catch { /* no subdir */ }
+    }
+
+    for (const filePath of filesToScan) {
+      if (/-orm\.ts$|-repo\.ts$|-repository\.ts$|repository\.ts$/.test(filePath)) continue
+      try {
+        const content = await readFile(filePath, 'utf-8')
+        const fileLines = content.split('\n')
+        let insideInterface = 0
+        for (let i = 0; i < fileLines.length; i++) {
+          const line = fileLines[i] ?? ''
+          if (/^\s*(export\s+)?interface\s+\w+/.test(line)) insideInterface++
+          const opens = (line.match(/\{/g) ?? []).length
+          const closes = (line.match(/\}/g) ?? []).length
+          if (insideInterface > 0) insideInterface = Math.max(0, insideInterface + opens - closes)
+          if (insideInterface > 0) continue
+          if (/^\s*findById\s*\([^)]*\)\s*:/.test(line)) continue
+          if (/\bfindById\s*\(/.test(line)) {
+            const window = fileLines.slice(i + 1, i + 6).join('\n')
+            if (!window.includes('assertOwnership') && !window.includes('userId') && !window.includes('ownerId')) {
+              violations.push({ type: 'IDOR_RISK', module: module.name, message: `"${relative(modulesPath, filePath)}" línea ${i + 1}: findById sin verificación de ownership. Usar auth.assertOwnership() para prevenir IDOR.` })
+              break
+            }
+          }
+        }
+      } catch { /* file unreadable */ }
+    }
+
+    // Service depends on ORM
+    if (/private\s+(readonly\s+)?\w+\s*:\s*ORM\b/.test(serviceContent)) {
+      violations.push({ type: 'SERVICE_DEPENDS_ON_ORM', module: module.name, message: `"${module.name}/service.ts" inyecta ORM directamente. Usar RepositoryAdapter<T> para poder swapear SQL → MongoDB → Prisma sin tocar el service. (CLAUDE #18)` })
+    }
+
+    // Model in types file
+    try {
+      const typesContent = await readFile(join(modPath, 'types.ts'), 'utf-8')
+      if (/\bModelDefinition\b/.test(typesContent)) {
+        violations.push({ type: 'MODEL_IN_TYPES_FILE', module: module.name, message: `"${module.name}/types.ts" contiene ModelDefinition o schema de DB. Moverlo a model.ts — son conceptos distintos. (CLAUDE #22)` })
+      }
+    } catch { /* no types.ts */ }
+
+    // Missing model.ts
+    if (!await fileExists(join(modPath, 'model.ts'))) {
+      violations.push({ type: 'MISSING_MODEL_TS', module: module.name, message: `"${module.name}" no tiene model.ts. El schema de DB debe vivir separado de types.ts. (CLAUDE #22)` })
+    }
+  }
+}

package/cli/analyze/index.ts

@@ -0,0 +1,44 @@
+import { access } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { AnalysisResult } from './types'
+import {
+  checkModuleStructure,
+  checkConnectors,
+  checkCrossImports,
+  checkConnectorLogic,
+  checkIndexFiles,
+  checkModuleQuality,
+} from './checks'
+
+export type { AnalysisResult, ModuleReport, Violation, Warning } from './types'
+export { printAnalysis, buildManifest } from './report'
+
+export async function analyzeProject(basePath: string): Promise<AnalysisResult> {
+  const violations: AnalysisResult['violations'] = []
+  const warnings: AnalysisResult['warnings'] = []
+
+  const srcPath = join(basePath, 'src')
+  const modulesPath = join(srcPath, 'modules')
+  const connectorsPath = join(srcPath, 'connectors')
+  const crPath = join(srcPath, 'composition-root.ts')
+
+  try {
+    await access(crPath)
+  } catch {
+    warnings.push({ type: 'NO_COMPOSITION_ROOT', message: 'No hay composition-root.ts en src/' })
+    return { valid: false, modules: [], connectors: [], violations, warnings }
+  }
+
+  const { modules, internalPaths } = await checkModuleStructure(modulesPath, violations, warnings)
+  const connectors = await checkConnectors(connectorsPath, crPath, modules, violations, warnings)
+
+  await Promise.all([
+    checkCrossImports(modulesPath, modules, violations),
+    checkConnectorLogic(connectorsPath, connectors, violations),
+    checkIndexFiles(modulesPath, modules, warnings),
+  ])
+
+  await checkModuleQuality(modulesPath, modules, internalPaths, violations, warnings)
+
+  return { valid: violations.length === 0, modules, connectors, violations, warnings }
+}