@path58/p58-n8n 0.2.12 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@path58/p58-n8n",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "The smartest and fastest n8n MCP server — validate, fix, and discover workflows inside your LLM",
   "keywords": [
     "mcp",
@@ -12,7 +12,7 @@
     "path58"
   ],
   "author": "Path58",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/tsvika58/p58-n8n#readme",
   "repository": {
     "type": "git",
@@ -26,6 +26,7 @@
   },
   "files": [
     "dist/mcp/server.bundle.cjs",
+    "src/data/public-catalog/**/*",
     "README.md",
     "AGENT_INSTALL.md",
     "CHANGELOG.md",
@@ -41,6 +42,7 @@
     "test": "vitest run",
     "test:unit": "vitest run --config vitest.unit.config.ts",
     "test:ci": "vitest run --config vitest.config.ci.ts",
+    "catalog:snapshot": "npx tsx src/scripts/production/catalog/generate-catalog-snapshot.ts",
     "backfill:classifications": "tsx src/scripts/production/classification/backfill-classifications.ts",
     "production:fix-rerun": "tsx src/scripts/production/comprehensive-fix-rerun-production.ts",
     "production:fix-rerun-simple": "tsx src/scripts/production/comprehensive-fix-rerun-simple.ts",

package/src/README.md

@@ -0,0 +1,188 @@
+# Source Code (`src/`)
+
+**Purpose:** Core source code for n8n workflow validator - validation logic, API, database clients, and utilities
+**Agent Entry Point:** Navigation hub for all source code modules
+**Human Entry Point:** Developer guide to source code organization
+**Standards:** Software Development Standards - Code Quality, Error Handling, Testing
+
+---
+
+## 🤖 Agent Entry Point
+
+**For AI Agents (RND, PM, Dev):**
+
+| Need | Go To |
+|------|-------|
+| **API routes & server** | [`api/`](api/) - REST API endpoints |
+| **Database clients** | [`db/`](db/) - PostgreSQL connection management |
+| **Validation logic** | [`validation/`](validation/) - L1-L5 validation system |
+| **Factory patterns** | [`factory/`](factory/) - Validation workflow factories |
+| **TypeScript scripts** | [`scripts/`](scripts/) - CLI scripts (693 files) |
+| **Embedding generation** | [`embedding/`](embedding/) - Text builders for embeddings |
+| **Services** | [`services/`](services/) - Business logic services |
+| **Utilities** | [`utils/`](utils/) - Shared utility functions |
+| **Error handling** | [`errors/`](errors/) - Error types and handlers |
+| **Testing utilities** | [`testing/`](testing/) - Test adapters and mocks |
+
+**Key Files:**
+- `api/server.ts` - Express API server (port 3000)
+- `db/validatorPostgresClient.ts` - Validator DB client (bluelime schema)
+- `validation/core.ts` - Core validation orchestrator
+- `factory/validation-config.ts` - Validation configuration
+
+---
+
+## 👤 Human Entry Point
+
+**For Developers:**
+
+| Need | Go To |
+|------|-------|
+| **Build API endpoints** | [`api/`](api/) - Add routes in `api/routes/` |
+| **Database operations** | [`db/`](db/) - Use clients from `db/` |
+| **Add validation rules** | [`validation/`](validation/) - Extend L1-L5 validators |
+| **Create scripts** | [`scripts/`](scripts/) - Add TypeScript scripts |
+| **Shared utilities** | [`utils/`](utils/) - Reusable helper functions |
+| **Error handling** | [`errors/`](errors/) - Use AppError types |
+
+---
+
+## 📁 Directory Structure
+
+```
+src/
+├── api/              # REST API server (Express)
+│   ├── routes/       # API route handlers
+│   └── middleware/   # Request middleware
+│
+├── db/               # Database clients
+│   ├── postgresClient.ts          # n8n DB client
+│   ├── scraperPostgresClient.ts   # Scraper DB client
+│   └── validatorPostgresClient.ts # Validator DB client (bluelime)
+│
+├── validation/       # Validation system (L1-L5)
+│   ├── l1-structure.ts   # Structure validation
+│   ├── l2-nodes.ts       # Node validation
+│   ├── l3-credentials.ts # Credential validation
+│   ├── l4-connections.ts # Connection validation
+│   ├── l5-parameters.ts  # Parameter validation
+│   └── core.ts           # Core orchestrator
+│
+├── factory/          # Factory pattern implementations
+│   ├── validation-config.ts           # Configuration
+│   ├── validation-workflow-loader.ts   # Workflow loading
+│   ├── validation-batch-runner.ts      # Batch processing
+│   └── validation-result-recorder.ts   # Result recording
+│
+├── scripts/          # TypeScript CLI scripts (693 files)
+│   ├── catalog/      # Catalog scripts (when organized)
+│   ├── validation/   # Validation scripts (when organized)
+│   └── ...
+│
+├── embedding/        # Embedding text builders
+│   ├── nodeTextBuilder.ts      # Node text generation
+│   ├── credentialTextBuilder.ts # Credential text generation
+│   └── aiNodeTextBuilder.ts    # AI node text generation
+│
+├── services/         # Business logic services
+│   ├── SearchService.ts        # Semantic search
+│   ├── EmbeddingService.ts     # Embedding generation
+│   ├── RankingService.ts      # Result ranking
+│   └── RedisCache.ts           # Caching layer
+│
+├── utils/            # Shared utility functions
+│   ├── logger.ts                # Logging utilities
+│   ├── scriptRunner.ts          # Script execution wrapper
+│   ├── connectionManager.ts     # Connection management
+│   └── ...
+│
+├── errors/           # Error types and handlers
+│   ├── AppError.ts   # Base error class
+│   └── README.md     # Error handling guide
+│
+├── testing/          # Testing utilities
+│   ├── k1/           # K1 level testing
+│   ├── k2/           # K2 level testing
+│   └── adapters/     # Test adapters
+│
+├── config/           # Configuration
+│   ├── env.ts        # Environment variable resolution
+│   └── scraperEnv.ts # Scraper environment
+│
+├── types/            # TypeScript type definitions
+├── data/             # Data constants (golden workflows, etc.)
+└── scraping/         # Web scraping utilities
+```
+
+---
+
+## 🔗 Navigation
+
+**Related Directories:**
+- [`../tests/`](../tests/) - Test files for source code
+- [`../docs/`](../docs/) - Documentation
+- [`../scripts/`](../scripts/) - Shell scripts
+
+**Parent Directory:**
+- [`../`](../) - Project root
+
+---
+
+## 📚 Standards
+
+**Relevant Standards:**
+- `/Users/tsvikavagman/Code Projects/.software-development-standards/01-code-quality/` - Code quality standards
+- `/Users/tsvikavagman/Code Projects/.software-development-standards/02-architecture/` - Architecture patterns
+- `/Users/tsvikavagman/Code Projects/.software-development-standards/05-testing/` - Testing standards
+
+**Key Standards Applied:**
+- Error handling: Mandatory type guards, AppError usage
+- Code quality: Clean code principles, SOLID patterns
+- Testing: AAA pattern, 80%+ coverage target
+- Script lifecycle: exp_, dbg_, tmp_, util_, dev_ prefixes
+
+---
+
+## 🚀 Quick Start
+
+### Adding a New API Route
+
+1. Create route file in `api/routes/`
+2. Import and register in `api/server.ts`
+3. Add Swagger documentation in `api/swagger.ts`
+
+### Adding a New Validator
+
+1. Create validator file in `validation/` (e.g., `l6-custom.ts`)
+2. Export validator function
+3. Register in `validation/core.ts`
+
+### Creating a Script
+
+1. Use `utils/scriptRunner.ts` wrapper
+2. Always close database connections
+3. Use lifecycle prefixes (exp_, dbg_, tmp_, util_, dev_)
+
+---
+
+## ⚠️ Critical Notes
+
+**Database Connections:**
+- Always use `executeScript()` wrapper from `utils/scriptRunner.ts`
+- Always call `shutdownValidatorPool()` in scripts
+- Use `bluelime` schema (v4.0), not deprecated `validator` schema
+
+**Error Handling:**
+- Always use `AppError` from `errors/AppError.ts`
+- Mandatory type guards for external data
+- Never throw raw errors
+
+**Testing:**
+- ALWAYS run tests with `-v` flag FIRST
+- NEVER pipe test output to files during first run
+- User MUST see tests running in real-time
+
+---
+
+**Last Updated:** January 1, 2026
+**Maintained By:** RND (Technical Lead)