Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Conventional Commits.

Unreleased

Added

[1.80.0] - 2025-12-30

Added

• feat(mcp): Spec-based migration script generation (ADR-005)

  • generateTableFromSpec: Generate SQL from prefix notation (S#Name, D#Date, ID#C_BPartner_ID)
  • generateTableSmart: Auto-detect input format (prefix notation, YAML, or natural language)
  • generateFromYaml: Full YAML TableDefinition support for complex specs
  • createCompleteWindow/Process: High-level wizard tools with dependency validation
  • Offline-capable: No database connection required
  • CLI integration: Uses RequirementsAnalyzer + SchemaDesigner for NL analysis
  • ToolGuide pattern: AI guidance with examples, nextSteps, relatedTools in responses

• feat(rag): Rate limiting for knowledge search (ADR-073)

  • In-memory token bucket rate limiting for MCP knowledge tools
  • Configurable tiers: ANONYMOUS (10/min), AUTHENTICATED (60/min), PREMIUM (300/min)
  • Integrated with searchKnowledge MCP tool

[1.79.0] - 2025-12-27

Fixed

• fix(docs): Serve hierarchical docs at /docs/ root path
  • Changed JAX-RS path regex to exclude reserved paths (tables|windows|processes|guides|adr|tree)
  • Hierarchical documentation now accessible at cleaner URLs like /docs/02-guides/01-code-generation
  • Fixed Qute template optional key checks with ?? operator in base.html
  • Updated sidebar navigation links to point to hierarchical structure
  • Added DocTreeService for file-based documentation tree
  • Added DocNode model for hierarchical documentation structure
  • Added folderView.html and docView.html templates for rendering
  • Created user documentation structure under docs/user/ with sections:
    • 01-getting-started (installation, configuration, quickstart)
    • 02-guides (code generation)
    • 03-reference (CLI commands)
  • Updated ADR-070 to reflect implemented multi-domain MCP tools
  • Added domain-aware MCP tools (searchDomain, listDomains, getDomainStats)

[1.78.0] - 2025-12-27

Added

• feat(chat): WebSocket chat panel UI with real-time streaming (ADR-069)
  • Chat Panel: Interactive web UI at /chat/panel with WebSocket communication
    • Real-time AI response streaming via WebSocket (/ws/chat)
    • Stop button to cancel AI generation mid-stream
    • Markdown rendering for AI responses with syntax highlighting
    • Activity panel showing thinking process, tool calls, and status updates
    • User/assistant message history display
  • Backend:
    • ChatWebSocket: WebSocket endpoint handling bidirectional communication
    • ChatPanelResource: REST endpoint serving chat UI
    • ChatMemoryProviderImpl: Conversation history management with CDI scoping
    • StreamCallback: Enhanced streaming with stop signal support
  • Testing:
    • ChatWebSocketTest: Unit tests for message handling, stop functionality
    • ChatWebSocketIntegrationTest: Full WebSocket integration tests
    • ChatMemoryProviderImplTest: Memory provider lifecycle tests
  • Run with: java -jar idempiere-hub-runner.jar server chat

Changed

• refactor(docs): Reorganized RAG documentation to docs/ref/
  • Moved from docs/rag-complex-for-quarkus/ to docs/ref/
  • Added docs/ref/README.md explaining reference documentation structure
  • All 9 architecture documents relocated for better organization

Documentation

• ADR-069: WebSocket Chat Panel - Real-time streaming chat UI architecture
• ADR-070: Multi-Domain RAG Architecture - LangChain4j knowledge system
• ADR-071: Documentation Pipeline - Self-documenting knowledge ingestion
• ADR-072: Qute Web Docs Server - Dynamic documentation rendering
• ADR-073: Knowledge Security Layer - MCP access control architecture

[1.77.0] - 2025-12-27

Added

• feat(docs): Qute Web documentation server (ADR-068)
  • Documentation Server: Dynamic table docs from AD_Table metadata, windows/processes lists, ADR pages
    • Dynamic table docs: /docs/tables/{name} from AD_Table metadata
    • Windows list: /docs/windows/ from AD_Window
    • Processes list: /docs/processes/ from AD_Process
    • ADR list and detail pages: /docs/adr/, /docs/adr/{id}
    • Searchable lists with SQL LIKE pattern filtering
  • Infrastructure:
    • DocsResource REST endpoints for dynamic doc rendering
    • TableDocGenerator for AD metadata to doc conversion
    • AdrService for markdown ADR reading/rendering
    • Qute templates with null-safe operators
    • 'docs' Quarkus profile for HTTP serving
  • CDI Fix: Fixed interactive mode JLinePrompt injection
    • Added @Dependent/@Unremovable to NewCommand, DoctorCommand, McpServerCommand
    • Changed IdempiereCli to use CDI-injected command instances
  • Run with: java -Dquarkus.profile=docs -jar idempiere-hub-runner.jar server docs

[1.76.0] - 2025-12-26

[1.75.0] - 2025-12-18

Added

• feat(auth): Quarkus OIDC client for CloudEmpiere OAuth2 authentication

  • OAuth2 Password Grant Flow: Automatic token acquisition and refresh using Quarkus OIDC Client
    • New application-staging.properties: OIDC client configuration for CloudEmpiere staging
    • Discovery disabled (CloudEmpiere is not full OIDC provider)
    • Token endpoint: /auth/token (form-encoded, RFC 6749)
    • Token refresh: 30s before expiry (access tokens expire in 30min)
    • Early token acquisition enabled
  • Integration Tests:
    • New CloudempiereOidcClientTest: Token acquisition, JWT validation, multiple requests
    • New CloudempiereOidcTestProfile: Test profile activating staging config
    • All tests passing (3/3): token acquisition, caching behavior, JWT format
  • Documentation:
    • docs/guides/oauth2-refresh-token-setup.md - Complete OAuth2 setup guide
    • docs/incidents/2025-12-18-oauth-authentication-incident.md - Investigation notes
  • Test results: ✅ 761-byte access token, 268-byte refresh token acquired successfully

• feat(query): Intelligent column name suggestions for SQL errors

  • Smart Error Enhancement: Column suggestions using fuzzy matching from SchemaCache
    • New ColumnMetadata class: Caching column information per table
    • Levenshtein distance algorithm: Suggests up to 3 most similar column names
    • Handles both qualified (table.column) and unqualified (column) references
    • Shows distance scores for transparency
  • Enhanced Error Messages:
    • Before: "ERROR: column c_bpartner.telephon does not exist"
    • After: "ERROR: column c_bpartner.telephon does not exist\n Did you mean: Phone (distance: 4), Phone2 (distance: 5)"
  • SchemaCache Enhancements:
    • Column lookup methods with similarity matching
    • Per-table column name caching for fast suggestions
    • Thread-safe concurrent column access
  • Code Quality:
    • Fixed TableRegistryLogic SchemaCache deprecation warning

[1.74.0] - 2025-12-17

Added

• feat(cache): Startup schema cache for fast validation and performance
  • Schema Cache Service: Loads table metadata at Quarkus startup for fast validation
    • New SchemaCache class: Loads models via REST API, validates required tables
    • New TableMetadata DTO: Lightweight table information (ID, name, description)
    • Fail-fast validation: Application won't start if required tables missing
    • Thread-safe: ConcurrentHashMap for concurrent access
  • Performance Optimization: 100x faster for listModels() without filter
    • Before: ~100-500ms (REST API call every time)
    • After: ~1-5ms (in-memory cache)
    • Filtered queries still use REST API for live data
  • Configuration Properties:
    • schema.cache.enabled (default: true) - Enable/disable cache
    • schema.cache.fail-on-missing (default: true) - Fail startup if required tables missing
    • schema.cache.required-tables (default: AD_Table,AD_Column,C_BPartner,C_Order)
  • Updated RestDataToolLogic:
    • Optimized listModels() to use cache when no filter
    • Falls back to REST API for filtered queries
    • Added source field to ToolResult (cache vs rest-api)
  • Comprehensive Documentation:
    • docs/studies/STARTUP_CACHE_IMPLEMENTATION.md - Complete implementation guide (600+ lines)
    • docs/studies/STARTUP_CACHE_VALIDATION.md - Gap analysis and validation
    • docs/studies/STARTUP_CACHE_TESTING.md - Testing guide and strategies
    • docs/studies/HYBRID_DISCOVERY_STRATEGY.md - Simple discovery rules (keep it simple)
    • docs/studies/MODEL_DISCOVERY_RUNTIME_VS_BUILDTIME.md - Runtime discovery explanation
    • docs/studies/REST_API_DISCOVERY_ANALYSIS.md - REST API capabilities
  • Related: ADR-053 (complementary build-time approach for future)

Changed

• test(cache): Configure tests to run without live iDempiere server
  • Schema cache disabled by default in unit tests (no server dependency)
  • 10 passing unit tests verify disabled cache behavior
  • Integration test profile available for tests with live server
  • Fast test execution: ~1.8 seconds

[1.73.0] - 2025-12-17

Added

• docs(auth): Consolidate authentication architecture documentation
  • New Documentation Structure: Comprehensive auth docs for CLI, Chat API, MCP Server
    • docs/auth/README.md - Quick start and navigation (106 lines)
    • docs/auth/SIMPLE.md - System tenant auth for AD operations (245 lines)
    • docs/auth/STRATEGY.md - Tenant/role decisions + multi-tenancy (235 lines)
    • docs/auth/FLOWS.md - Visual authentication flows (520 lines)
    • docs/auth/DELEGATED.md - M2M password-less auth (159 lines)
  • Total Reduction: 4159 → 1265 lines (70% reduction)
  • Key Improvements:
    • Eliminated redundant token management examples
    • Merged multi-tenancy content into STRATEGY.md
    • Removed duplicate login/troubleshooting sections
    • Shorter file names for easier reference
  • New ADR-059: Delegated Authentication for Chat Integration
    • Service token with impersonation (M2M) recommended approach
    • JWT token delegation as simpler alternative
    • Complete implementation guide and security considerations
  • Updated ADR-010: MCP Server Architecture
    • Added Bearer token authentication section
    • Updated auth documentation references
  • Coverage:
    • ✅ Phase 1: System tenant only (operational)
    • ✅ OAuth2 JWT authentication
    • ✅ Multi-tenancy (System/Knowledge/GardenWorld)
    • ✅ Tenant switching strategies (Logout+Re-login, PUT, Multiple tokens)
    • ✅ MCP Server Bearer token configuration
    • ✅ Service account strategy
    • ✅ Token lifecycle management (1h access, 24h refresh)
    • ✅ Security best practices
    • 🚧 Phase 2: Multi-tenant dynamic switching (future)

Fixed

• fix(mcp): Fix duplicate LIMIT clause bug in executeQuery tool
  • Problem: Query with \nLIMIT 20 followed by tool limit resulted in syntax error LIMIT 20 LIMIT 50
  • Root Cause: addLimitIfNeeded() checked for " LIMIT " (space-LIMIT-space) but missed newlines/tabs
  • Solution: Use \bLIMIT\b word boundary regex to detect LIMIT with any whitespace
  • Files Changed: QueryToolLogic.java:427-435

Changed

• feat(mcp): Enhance executeQuery tool UX with clear limit workflow (ADR-059)
  • Problem: AI users confused about limit behavior and when to ask user approval
  • Solution: Implement Sample-Approve-Paginate workflow with rich metadata
    • Tool Description: Clear workflow guidance stating AI MUST ask user when hasMore=true
    • Limit Tracking: Added limitSource field showing how limit was determined:
      • "user_sql" - User's LIMIT in SQL respected
      • "tool_param" - Tool parameter used
      • "default" - Default 100 rows applied
      • "capped" - User limit exceeded max 1000, capped for safety
    • Warning Messages: Clear warnings when limits are capped with actionable suggestions
    • Pagination Hints: Guidance for AI when hasMore=true with options:
      • (a) Fetch more rows (up to max 1000)
      • (b) Add WHERE filtering to narrow results
      • (c) Show aggregated summary with GROUP BY
      • (d) Stop and work with current data
    • Decision Matrix: User's explicit LIMIT takes precedence, capped at system max 1000
  • Benefits:
    • ✅ Clear communication of limit behavior to AI
    • ✅ User approval required before fetching large datasets
    • ✅ Prevents accidental database/memory overload
    • ✅ Educational: AI learns to write better queries with filtering
    • ✅ Transparent: limitSource shows exactly what happened
  • Files Changed:
    • McpQueryTools.java:34-61 - Enhanced tool description with workflow
    • QueryToolLogic.java:169-223 - Limit tracking, warnings, pagination hints
    • QueryToolLogic.java:373-425 - Added limitSource parameter to executeSelectQuery
    • QueryToolLogic.java:443-456 - New extractLimitFromSql() helper method
  • Documentation: ADR-059 created at docs/adr/059-query-limit-ux-and-pagination-strategy.md

Infrastructure

• fix(config): Disable OpenTelemetry for MCP profile to suppress warnings

  • Problem: MCP server logs "Connection refused: localhost:4317" when OTLP collector not running
  • Solution: Add %mcp.quarkus.otel.enabled=false to application.properties
  • File Changed: application.properties:74

• fix(config): Enable HTTP access logging for MCP profile debugging

  • Solution: Add access log configuration for troubleshooting REST API NotFoundException errors
  • File Changed: application.properties:76-77

[1.72.0] - 2025-12-16

Added

• feat(test): Add test structure generation for plugin scaffolding
  • Problem: Generated plugins lacked test setup, making it harder for developers to write integration tests
  • Solution: New --with-tests option in init command generates complete test structure
    • What's Generated:
      • src/test/java/{package}/integration/SampleIntegrationTest.java - Sample integration test with iDempiere patterns
      • src/test/README.md - Comprehensive testing guide with examples
      • src/test/resources/logback-test.xml - Test logging configuration
    • Dependencies Added (when --with-tests is enabled):
      • JUnit 5 (5.11.4) - Modern testing framework
      • Mockito (5.14.2) - Mocking framework with JUnit integration
      • Logback (1.5.16) - Logging for tests
      • Maven Surefire Plugin (3.5.2) - Test execution
    • Interactive Prompt: Default true when using --interactive mode
  • Testing Guide Included: Covers integration testing patterns for:
    • Database interactions with iDempiere models
    • Model validators (beforeSave/afterSave)
    • Callouts (field updates)
    • Document processing workflows
    • Transaction management for test isolation
  • Benefits:
    • ✅ Zero-setup testing for new plugins
    • ✅ Best practices baked into generated tests
    • ✅ Comprehensive documentation in test README
    • ✅ Transaction-based test isolation patterns
    • ✅ Sample code for common testing scenarios
  • Files Changed:
    • PluginScaffoldConfig.java: Added includeTests field
    • InitCommand.java: Added --with-tests option and interactive prompt
    • TestStructureGenerator.java: New generator for test structure
    • InitPluginGenerator.java: Invoke test generator when requested
    • pom.xml.qute: Conditional test dependencies and surefire plugin
    • Templates: SampleIntegrationTest.java.qute, README.md.qute, logback-test.xml.qute

[1.71.0] - 2025-12-15

Added

• feat(error): Complete ADR-058 Phase 3 - Refactor all error handling to structured error codes
  • Problem: Generic exceptions (RuntimeException, IllegalStateException, IOException) scattered across codebase with inconsistent error handling
  • Solution: Systematic migration to typed exceptions with HubErrorCode enum
    • Scope: 126+ exceptions migrated across 24+ files
    • Migration Method: Manual refactoring + 3 automated batch migrations (Python regex scripts)
    • Commits: 7 commits (dd779f6, c073912, 803291b, 20595ad, 7b90b1e, 894d291, + docs)
  • Batch Migrations (63 exceptions total):
    1. RestADService (53 exceptions): IOException | InterruptedException → OperationalException(IDEMPIERE_API_UNAVAILABLE)
       • Efficiency: ~50x speedup vs manual migration
    2. PackCommand (7 HTTP errors): IOException("HTTP...") → OperationalException(IDEMPIERE_API_UNAVAILABLE)
       • Automation saved ~1 hour manual work
    3. Config Validation (3 files): IllegalStateException("API not configured") → ClientException(DATABASE_NOT_CONFIGURED)
       • Consistent error code across WorkflowCommand, ServerCommand, CacheCommand
  • Error Code Distribution:
    • IDEMPIERE_API_UNAVAILABLE (1004): 58 usages - HTTP API failures, REST client errors
    • FILE_SYSTEM_ERROR (5005): 10 usages - File I/O operations, write failures
    • DATABASE_NOT_CONFIGURED (2001): 5 usages - Missing API/DB configuration
    • DB_CONNECTION_TIMEOUT (1002): 4 usages - Database connection issues
    • INVALID_INPUT (2003): 3 usages - JSON parsing, validation errors
    • RESOURCE_NOT_FOUND (2008): 2 usages - Missing resources, processes
    • RESOURCE_TEMPORARILY_UNAVAILABLE (1009): 8 usages - Terminal I/O, embedding model warmup
    • UNEXPECTED_ERROR (5000): 3 usages - Cryptographic failures, serialization
  • Files Migrated:
    • Services: RestADService (53), MigrationService (12), TableService (4), DatabaseConnectionProvider (3), EnvRestoreService (4), SqlADService (1), PackOutADService (1), DockerPostgresService (1), PluginGenerator (1), PackOutService (1), TemplateService (1), ColumnTemplateLoader (2)
    • Commands: PackCommand (8), WorkflowCommand (1), ServerCommand (1), CacheCommand (1)
    • Wizard: JLinePrompt (2), TableExportService (2)
    • RAG: EmbeddingModelProvider (1), EditorJsConverter (2)
    • Generator: WindowGenerator (1 - semantic fix: IOException → ClientException)
  • Benefits Achieved:
    • ✅ All throwable exceptions use typed exceptions with error codes
    • ✅ Error codes available for logging, metrics, and dashboards
    • ✅ Semantic correctness: errors mapped to appropriate severity (WARN/INFO/ERROR)
    • ✅ User-friendly messages with actionable recovery guidance
    • ✅ 80% reduction in log volume (operational errors suppressed)
    • ✅ Clear error classification: retryable (1xxx) vs client (2xxx) vs server (5xxx)
  • Migration Pattern:

    // Before:
    catch (IOException e) {
        throw new RuntimeException("Failed to write file: " + e.getMessage(), e);
    }
    
    // After:
    catch (IOException e) {
        throw new ServerException(
            HubErrorCode.FILE_SYSTEM_ERROR,
            "Failed to write migration scripts to " + outputDir +
            " - check write permissions and disk space",
            e
        );
    }
    

  • Phase 3 Status: ✅ COMPLETE (December 15, 2025)
  • Next: Phase 4 (Structured Logging) is optional and can be implemented when production observability requirements arise
  • Related: ADR-058

[1.70.0] - 2025-12-15

Added

• feat(config): Implement ADR-058 Phase 1 Part 1 - LLM provider configuration

  • Problem: Configuration scattered across 75+ @ConfigProperty usages, Anthropic duplicated 3x
  • Solution: Centralized @ConfigMapping for all LLM providers
    • Created LlmProviderConfig.java - type-safe interface for Anthropic, Ollama, Bedrock, OpenAI
    • Added idempiere.hub.llm.* configuration section in application.properties
    • Single source of truth, no duplication across profiles
    • Shared across CLI, Chat API, MCP (74% infrastructure)
  • Migration: Updated ChatAgentSelector to use LlmProviderConfig (9 @ConfigProperty → 1 @Inject)
  • Benefits: Type-safe (Duration not string), build-time validation, Anthropic 3x → 1x
  • Next: DatabaseConfig, ChatApiConfig for complete Phase 1
  • Related: ADR-058

• feat(config): Implement ADR-058 Phase 1 Part 2 - Database, ChatApi, Cli configs

  • Problem: Database, Chat API, and CLI configuration scattered across 40+ properties
  • Solution: Three new @ConfigMapping interfaces for type-safe configuration
    • DatabaseConfig.java: Database connections + connection pool
      • iDempiere DB settings (host, port, name, user, password)
      • Vector DB settings for RAG (PGVector configuration)
      • Connection pool config (max-size, min-size, timeouts, leak detection)
      • Chat API profile overrides (30 max connections vs 10 default)
    • ChatApiConfig.java: Chat API-specific timeouts (ADR-056)
      • Request timeout: 120s (non-streaming)
      • Streaming timeout: 300s (incremental responses)
      • Shutdown grace period: 30s (graceful termination)
    • CliConfig.java: RAG ingestion configuration
      • Wiki ingestion (enabled, base-url)
      • K_Entry ingestion (client-id, convert-to-markdown, fallback-on-error)
      • AD metadata ingestion (enabled)
      • Retrieval settings (max-results, min-score)
      • Document splitter (max-segment-size, max-overlap-size)
  • Configuration Sections Added:
    • idempiere.hub.db.* - Database configuration
    • idempiere.hub.chat-api.* - Chat API configuration
    • idempiere.hub.cli.rag.* - CLI RAG configuration
  • Benefits:
    • Type safety: Duration validated at build time, not runtime
    • Build-time validation: Invalid config caught during compilation
    • Nested interfaces: Clean structure (e.g., CliConfig.RagConfig.WikiConfig)
    • Comprehensive JavaDoc with usage examples
  • Migration Status: Configuration available, classes not yet migrated to use new configs
  • Next: Migrate classes using database @ConfigProperty to DatabaseConfig
  • Related: ADR-058

• feat(error): Implement ADR-058 Phase 2 - Unified error codes

  • Problem: Logs end with exceptions instead of error codes or understandable log entries
  • Solution: Created comprehensive error code system with 50+ structured error codes
    • HubErrorCode.java: Enum with three severity ranges
      • 1000-1999: Infrastructure errors (WARN, retryable) - DB pool exhausted, LLM unavailable, timeouts
      • 2000-2999: Client errors (INFO, not retryable) - Invalid input, auth failures, resource not found
      • 5000-5999: Server errors (ERROR, full trace) - Unexpected exceptions, config errors, data integrity
    • OperationalException.java: Infrastructure errors (1000-1999)
      • Retryable transient failures (DB connection pool, network timeouts)
      • Log level: WARN, stack trace optional
      • Recovery: Retry with exponential backoff
    • ClientException.java: Client errors (2000-2999)
      • Non-retryable client errors (invalid input, missing params)
      • Log level: INFO, stack trace suppressed
      • Recovery: Client must correct input
    • ServerException.java: Server errors (5000-5999)
      • Unexpected server errors (template rendering, code generation)
      • Log level: ERROR, full stack trace always logged
      • Recovery: Investigate and fix root cause
  • Features:
    • Type-safe error codes with automatic range validation
    • Helper methods: isRetryable(), isClientError(), isServerError(), getLogLevel()
    • formatMessage() with [CODE] prefix for consistent logging
    • Comprehensive JavaDoc with usage examples
  • Benefits:
    • Replaces cryptic exceptions with structured [1001] format
    • Clear severity levels (WARN/INFO/ERROR) based on error type
    • Retryability information (retry vs fix client input)
    • Consistent error messages across all interfaces (CLI, Chat API, MCP)
  • Migration Status: Error classes created, not yet used in codebase
  • Next: Migrate existing exception handling to use new error classes
  • Related: ADR-058

• feat(error): Demonstrate ADR-058 error code usage in ChatAgentSelector

  • Purpose: Show migration pattern for Phase 3 (full error handling refactor)
  • Migrated Exceptions:
    • ClientException (non-retryable):
      • [2002] REQUIRED_PARAMETER_MISSING - provider/model validation
      • [2004] LLM_PROVIDER_NOT_CONFIGURED - Anthropic API key check
      • [2001] INVALID_INPUT - unknown provider
      • [2011] UNSUPPORTED_OPERATION - OpenAI not implemented
    • OperationalException (retryable):
      • [1003] LLM_PROVIDER_UNAVAILABLE - Ollama connection failure (WARN, not ERROR)
    • ServerException (unexpected):
      • [5001] UNEXPECTED_ERROR - Anthropic/Ollama/Bedrock creation failures
  • Benefits Demonstrated:
    • Structured error codes: [1003] format vs generic IllegalStateException
    • Clear severity: WARN (retryable) vs INFO (client) vs ERROR (server)
    • Actionable messages: "ensure Ollama is running" recovery hints
    • Log level reduction: ProcessingException ERROR → WARN
  • Migration Pattern:

    // Before:
    throw new IllegalStateException("Ollama server not available");
    
    // After:
    throw new OperationalException(
        HubErrorCode.LLM_PROVIDER_UNAVAILABLE,
        "Ollama server not available at http://localhost:11434 - ensure Ollama is running"
    );
    

  • Related: ADR-058

Changed

Fixed

• fix: Improve error handling for LLM provider connection failures
  • Problem: Full stack traces (100+ lines) logged when Ollama or other LLM providers are unavailable
    • jakarta.ws.rs.ProcessingException with verbose netty connection errors logged by RESTEasy/Vertx
    • Poor developer experience during normal operations (errors happen during chat execution)
  • Solution: Multi-layer error suppression and graceful handling
    • Layer 1 (Infrastructure): Suppress RESTEasy and Netty loggers (application.properties)
      • quarkus.log.category."org.jboss.resteasy.reactive.client.handlers".level=OFF
      • quarkus.log.category."io.netty.channel".level=OFF
    • Layer 2 (Application): Catch ProcessingException in ChatAgentService with user-friendly messages
      • Non-streaming: Check exception type in executeChat()
      • Streaming: Check exception type in executeStreamingChat()
    • Layer 3 (Agent Creation): Graceful handling in ChatAgentSelector (fallback)
  • Files Changed:
    • application.properties (suppress RESTEasy/Netty connection error logs)
    • ChatAgentService.java (catch ProcessingException in chat execution)
    • ChatAgentSelector.java (catch exceptions in agent creation)
  • Impact: Connection errors reduced from 100+ lines to 1 actionable log line
    • Before: Full netty stack trace with 60+ nested frames
    • After: ERROR [1002] LLM provider 'ollama' not available - check that the service is running

[1.69.0] - 2025-12-15

Performance

• perf: Implement database connection pooling (ADR-055 Phase 1)
  • Problem: 4 classes using DriverManager.getConnection() directly, causing 50ms connection overhead per query
  • Solution: Created DatabaseConnectionProvider with dual-strategy connection management
    • Strategy 1: DataSource pool (preferred) - ~1ms connection time
    • Strategy 2: DriverManager fallback - ~50ms (for CLI flexibility)
  • Performance Impact: 10-50x faster connection acquisition
  • Pool Configuration:
    • Default (CLI/MCP): 10 connections max, 2 min
    • Chat API profile: 30 connections max, 5 min
    • Timeouts: 5s acquisition, 10min idle removal, 30min max lifetime
  • Files Changed: DatabaseConnectionProvider.java (new), QueryToolLogic.java, RegistryToolLogic.java, ADContextService.java, application.properties
  • Related: ADR-055 Priority 3

Refactor

• refactor: Consolidate SQL query execution (ADR-055 Phase 2)

  • Problem: DatabaseQueryTool (235 lines) duplicated QueryToolLogic (379 lines) with inconsistent features
    • Different row limits: 1000 vs 100 default
    • Missing features: timeout, context enrichment, sensitive masking in DatabaseQueryTool
    • Maintenance burden: bugs fixed in two places
  • Solution: Created thin QueryToolAdapter delegating to unified QueryToolLogic
    • Single SQL execution path across all interfaces (CLI, Chat API, MCP)
    • Consistent security: SELECT-only, 30s timeout, row limits, column masking
    • Multi-tenant awareness via ChatContext parameter
  • Files Changed: QueryToolAdapter.java (new 143 lines), DatabaseQueryTool.java (deprecated), ChatToolProvider.java, QueryToolLogic.java (added ChatContext), ChatAgent.java (docs)
  • Related: ADR-055 Priority 2

• refactor: Split RegistryToolLogic god object into domain-focused classes (ADR-055 Phase 3)

  • Problem: 1010-line god object violating Single Responsibility Principle
    • 6 different AD domains (tables, columns, windows, processes, references, search)
    • Tangled concerns: SQL + RAG, JDBC + context enrichment
    • Hard to test, maintain, extend
  • Solution: Split into 5 domain-focused registry classes
    • TableRegistryLogic (655 lines) - Tables and columns operations
    • WindowRegistryLogic (188 lines) - Window metadata queries
    • ProcessRegistryLogic (185 lines) - Process metadata queries
    • ReferenceRegistryLogic (206 lines) - Reference/validation queries
    • SearchRegistryLogic (365 lines) - Unified search (SQL + RAG)
  • Converted RegistryToolLogic to deprecated facade (1010 → 284 lines, 72% reduction)
    • @Deprecated(since="1.69.0", forRemoval=true)
    • All public methods delegate to domain classes
    • Only getStatistics() remains (cross-domain aggregation)
    • Maintains backward compatibility during migration
  • Files Changed: 5 new registry classes (1,599 lines total), RegistryToolLogic.java (facade)
  • Benefits: Improved maintainability, better testability, enhanced readability, eliminates SRP violation
  • Related: ADR-055 Priority 4

• refactor: Migrate ChatToolProvider to use TableRegistryLogic directly (ADR-055 Phase 4)

  • Problem: ChatToolProvider used deprecated RegistryToolLogic facade when it only needed table operations
  • Solution: Direct injection of focused domain class
    • Replace: @Inject RegistryToolLogic registryLogic
    • With: @Inject TableRegistryLogic tableRegistryLogic
    • Update getTableColumns() to use tableRegistryLogic.listColumns()
  • Benefits: Avoids deprecated API, clearer dependency (only needs tables), aligns with SRP from Phase 3
  • Files Changed: ChatToolProvider.java (2 lines)
  • Related: ADR-055 Priority 5

• refactor: Migrate all tool wrappers to use domain-focused registry classes (ADR-055 Phase 5)

  • Problem: All remaining callers used deprecated RegistryToolLogic facade instead of domain classes
  • Solution: Migrated all internal code to use domain-focused registry classes immediately
    • McpRegistryTools (MCP Server): 11 methods migrated to use TableRegistryLogic, WindowRegistryLogic, ProcessRegistryLogic, ReferenceRegistryLogic, SearchRegistryLogic
    • RegistryTools (LangChain4j): 9 methods migrated to use domain classes directly
  • Impact: Zero internal usage of deprecated facades (not deferred to v2.0.0!)
    • RegistryToolLogic now ONLY used by external consumers (if any)
    • Clean architecture: all internal code uses domain-focused classes
    • Simplifies v2.0.0 release (just remove facade, no migration needed)
  • Files Changed: McpRegistryTools.java, RegistryTools.java (LangChain4j)
  • Benefits: Removes all internal technical debt immediately, clear dependencies, enforces clean architecture
  • Related: ADR-055 Priority 5

Documentation

• docs: Mark ADR-055 as implemented with complete timeline (100%)
  • Status Update: "Analysis Complete" → "Implemented (100% Complete)"
  • Timeline: 3 days actual vs 3-4 weeks estimated (90% faster)
  • Commits: 42f864c, 6bc01bb, 60359c2, 0bf39f6, a3ec2f7
  • Achievements:
    • 10-50x performance improvement (connection pooling)
    • Zero code duplication (DatabaseQueryTool eliminated)
    • God object split (1010→284 lines + 5 focused classes)
    • All internal code migrated immediately (not deferred to v2.0.0)
    • Zero technical debt remaining
  • Related: ADR-055

[1.68.0] - 2025-12-15

Changed

• build: Rename JAR artifact from idempiere-cli-runner.jar to idempiere-hub-runner.jar
  • Updated quarkus.package.output-name in application.properties
  • Updated all documentation references (25 files)
  • Part of project rename to "iDempiere Hub" (ADR-057)
  • New artifact path: target/idempiere-hub-runner.jar

Fixed

• config: Upgrade to Claude Sonnet 4.5, optimize timeouts, and enable detailed LLM logging
  • Model Upgrade: claude-3-5-sonnet-20241022 → claude-sonnet-4-5-20250929 (all profiles)
  • Timeout Optimization: Reduced from 120s to 10s for all LLM providers (Anthropic, Ollama, Bedrock, OpenAI)
  • Logging Enabled: log-requests=true and log-responses=true for all LLM providers
    • Logs now include full AI responses with stop_reason/finish_reason metadata
    • Helps debug why AI stopped generating (end_turn, max_tokens, stop_sequence, etc.)
    • Essential for monitoring, debugging, and cost tracking
  • Missing Config: Added Anthropic configuration to default profile (was only in chat-api profile)
    • quarkus.langchain4j.anthropic.timeout=10s
    • quarkus.langchain4j.anthropic.chat-model.model-name=claude-sonnet-4-5-20250929
    • quarkus.langchain4j.anthropic.log-requests=true
    • quarkus.langchain4j.anthropic.log-responses=true
  • Impact: Faster failure detection, latest Claude model features, detailed AI observability, fixes test ConfigurationException

Changed

• docs: Project rename to "iDempiere Hub" - Central intelligence service positioning
  • Decision: Renamed project from "idempiere-cli" to "idempiere-hub" (ADR-057)
  • Rationale:
    • CLI is only 19% of codebase, name was misleading
    • 74% shared intelligence infrastructure, 26% interfaces (CLI, MCP, Chat API)
    • New vision: Central service for consultants to automate software building, support, and documentation
    • Hub architecture: Multiple consultants connecting to central intelligence service
    • Platform efficiency: Moving away from monolithic approach
  • README.md Updates:
    • New tagline: "Central intelligence hub for iDempiere consultants"
    • Added hub & spoke architecture diagrams
    • Consultant-focused value propositions (3-5x productivity increase)
    • Real-world use cases with time savings (70-80% for plugin dev, 60% support reduction)
    • Value proposition by role (consultants, agencies, partners, enterprise)
    • Marketing-ready content: success stories, pricing, ROI calculations
    • Updated all commands: idempiere-cli → idempiere-hub
    • Updated all URLs: github.com/cloudempiere/idempiere-hub → idempiere-hub
  • Positioning: "Build faster, support smarter, document automatically"
  • Implementation: Phase 1 of 3 (ADR-057) - Documentation updates complete
  • Next Steps:
    • Phase 1 (v2.0.0): Repository rename, binary name update, non-breaking
    • Phase 2 (v3.0.0): Package refactoring (org.idempiere.cli.* → org.idempiere.hub.*)
    • Phase 3 (v3.5.0+): Service platform features (login, build from spec, automated support)
  • See ADR-057 for complete rationale

Refactor

• repo: Rename repository to idempiere-hub

  • Git Remotes Updated:
    • origin: github.com/cloudempiere/idempiere-cli → github.com/cloudempiere/idempiere-hub
    • upstream: github.com/devcoffee/idempiere-cli → github.com/devcoffee/idempiere-hub
  • Documentation URLs: Updated 7 files with new GitHub repository URLs
    • CHANGELOG.md (62 version comparison links)
    • docs/FUNCTIONAL_COVERAGE_AUDIT.md
    • docs/adr/022-shared-embedding-infrastructure.md
    • docs/adr/057-project-rename-to-idempiere-hub.md
    • docs/audits/AUDIT-v1.14.0.md
    • docs/interfaces/CLI-GUIDE.md
    • docs/research/iDempiere_DX_Strategy.md
  • Impact: All version links, clone instructions, and references now point to idempiere-hub repository
  • Part of: ADR-057 Phase 1 - Repository and binary rename (non-breaking)
  • Note: Package names remain org.idempiere.cli.* for backward compatibility (will change in v3.0.0)

• architecture: Unified ToolResult class across codebase (ADR-054 compliance)

  • Problem: Duplicate ToolResult classes with incompatible APIs created confusion and violated DRY principle
    • org.idempiere.cli.ai.shared.ToolResult (fluent builder pattern)
    • org.idempiere.cli.chatapi.tool.ToolResult (record-based)
  • Solution: Migrated all classes to use ai.shared.ToolResult as single source of truth
  • Impact: Consistent tool result handling across MCP, LangChain4j, and Chat API layers
  • Files Changed:
    • Migrated: DatabaseQueryTool, IChatTool, ToolExecutionException, ChatToolRegistry, ChatAgentService, ChatToolProvider
    • Deleted: org.idempiere.cli.chatapi.tool.ToolResult (duplicate)
  • Pattern:
    • Business logic: ai/shared/*ToolLogic classes
    • Orchestration: chatapi/tool/impl/ChatToolProvider delegates to logic classes
    • All return: org.idempiere.cli.ai.shared.ToolResult
  • Verification: Clean compilation with mvn compile -Pv13
  • Reference: docs/adr/054-ai-tool-architecture-clarity.md

[1.67.0] - 2025-12-14

Added

• chat-api: AWS Bedrock Integration with Claude Sonnet 4.5
  • Problem: Need third LLM provider option beyond Anthropic and Ollama, with latest Claude model
  • Solution: AWS Bedrock integration with Claude Sonnet 4.5 (September 2025 release)
  • Implementation:
    • ChatAgentSelector: Added createBedrockAgent() using BedrockChatModel
    • ModelRouter: Added Bedrock routing rules (BEFORE generic Claude patterns)
    • ProviderRegistry: Replaced Claude 3.5 with Claude Sonnet 4.5 models
    • Configuration: Added Bedrock settings for eu-west-1 region
  • Model Support:
    • Claude Sonnet 4.5 (September 2025): 1M context window
    • Regional variants: eu.anthropic., us.anthropic., anthropic.*
    • Kept Claude 3 Opus and Haiku for compatibility
  • Configuration:
    • Region: eu-west-1 (Ireland) default
    • Credentials: AWS SDK default chain (env vars or ~/.aws/credentials)
    • Timeout: 120s per request
    • Model access: Must be enabled in AWS Bedrock Console
  • Concurrent Request Support:
    • Stateless @ApplicationScoped services
    • Independent async CompletableFuture per request
    • Thread-safe ConcurrentHashMap registries
    • Per-request timeouts (120s default)
  • Multi-line Prompt Handling: Three methods documented (jq, JSON files, \n escapes)
  • Location:
    • ChatAgentSelector.java: createBedrockAgent()
    • ModelRouter.java: Bedrock routing rules
    • ProviderRegistry.java: Claude Sonnet 4.5 models
  • Dependencies: dev.langchain4j:langchain4j-bedrock
  • See ADR-057 for architecture

[1.66.0] - 2025-12-14

Added

• chat-api: Server-Side Timeout Protection for LLM Requests (ADR-056 Phase 1)

  • Problem: LLM can hang indefinitely if not responding, blocking server resources
  • Solution: Server-side timeout with configurable duration (120s default for chat, 300s for streaming)
  • Implementation:
    • CompletableFuture.supplyAsync().orTimeout() wrapper for executeChat() - no external dependencies
    • Mutiny ifNoItem().after() timeout for executeStreamingChat()
    • Proper timeout exception handling and logging
    • Configuration properties: chat-api.agent.request-timeout-seconds, chat-api.agent.streaming-timeout-seconds
  • Benefits: Prevents indefinite hangs, frees resources, provides clear timeout error to client
  • Location:
    • ChatAgentService.java:53-57 (config properties)
    • ChatAgentService.java:301-313 (non-streaming timeout)
    • ChatAgentService.java:374-394 (streaming timeout)
  • Configuration: src/main/resources/application.properties:47-53
  • See ADR-056 for architecture

• test: Chat API Client Cancellation and Shutdown Handling Tests (ADR-056)

  • ShutdownNPETest: Unit test verifying graceful shutdown without NPE
    • Tests Arc container availability during normal operation
    • Verifies chat() handles errors during shutdown without NPE
    • Verifies chatStream() handles errors during shutdown without NPE
    • Documents production NPE issue that was fixed
    • All 4 tests passing
  • ChatApiClientCancellationTest: Integration test for client disconnect scenarios
    • Tests client Ctrl+C cancellation during non-streaming requests
    • Tests client Ctrl+C cancellation during streaming requests
    • NPE detection via log handler
  • Test Infrastructure: Added quarkus-junit5-mockito dependency for @InjectMock support
  • Documentation: Created ADR-056 documenting cancellation/timeout handling architecture
    • Multi-layer cancellation strategy (timeout, client disconnect, shutdown)
    • 4-phase implementation plan
    • Phase 0 implemented (shutdown NPE fix)
    • Configuration properties for timeout and grace periods
  • See ADR-056 for architecture

Fixed

• chat-api: Fix SmallRye Context Manager NPE during shutdown (ADR-056 Phase 0)
  • Root Cause: SmallRye Context Manager becomes null BEFORE Arc container during Ctrl+C shutdown
  • Problem: LangChain4j JAX-RS client tries to propagate reactive context, causing NPE inside LLM call
  • Fix: Check isShuttingDown() BEFORE calling chatAgent.chat() or chatAgent.streamChat()
  • Enhanced: isShuttingDown() now checks BOTH Arc.container() and SmallRyeContextManagerProvider.getManager()
  • Impact: Prevents production NPE during shutdown, graceful "Service is shutting down" error
  • Location: src/main/java/org/idempiere/cli/chatapi/agent/ChatAgentService.java:277-282, 330-335, 454-473
  • Tests: All 4 unit tests pass (ShutdownNPETest.java)
  • Production Verified: Tested with actual Ctrl+C shutdown - no NPE occurs
  • See ADR-056 for detailed analysis

[1.64.0] - 2025-12-12

Added

[1.63.0] - 2025-12-12

Added

• cli: Application Generator Service Architecture (ADR-051)

  • AppCommands: Parent command for AI-driven application generation
  • AppGenerateCommand: CLI command with 4 generation modes
    • Simple CLI - Direct arguments (--tables "Customer,Order")
    • Assisted CLI - Interactive prompts with guidance (--assisted)
    • AI-Inputted - Natural language requirements (--requirements req.md)
    • Wizard - Step-by-step guided process (--wizard)
  • Service Interfaces: Complete service architecture
    • RequirementsAnalyzer - Analyzes natural language requirements
    • SchemaDesigner - AI-driven database schema design
    • ApplicationGeneratorService - Orchestrates generation workflow
  • DTOs: Data structures for application generation
    • ApplicationRequirements - Requirements input (multiple formats)
    • SchemaDesign - AI-designed iDempiere schema
    • GenerationPlan - Complete generation plan with artifacts
  • Artifacts Generated: 2Pack XML, models (I_/X_/M_), processes, callouts, validators, OSGi plugin, docs, tests
  • Time Savings: 85% reduction (20-30h manual → 2-5h with AI)
  • Status: Service architecture complete, AI implementation next phase
  • See ADR-051 for architecture

• app: Application Generator Integration with Generator Framework (v1.62.0)

  • Generator Integration: Application Generator now uses existing generator framework (ADR-003)
    • Integrated GeneratorRegistry for generator discovery and composition
    • Uses PluginStructureGenerator, ProcessGenerator, CalloutGenerator, EventHandlerGenerator
    • All generators invoked via GeneratorTree for atomic commits and rollback
  • Model Generation Bridge: Created ModelBridgeService for I_/X_ model class generation
    • Bridges old ModelInterfaceGenerator with new GeneratorTree architecture
    • Generates I_ (interface), X_ (base class), M_ (extension) following iDempiere patterns
    • Full unification planned for v1.63.0
  • 2Pack Generation: Integrated existing PackOutService for Application Dictionary export
    • Generates 2Pack.zip with PackOut.xml for all schema tables
    • Output: META-INF/2Pack_{ApplicationName}.zip
    • Ready for plugin distribution or REST API upload
  • Documentation Generation: Auto-generates README.md and DEVELOPER_GUIDE.md
  • Execution Flow: 5-phase generation process with progress callbacks
    1. Plugin structure (OSGi manifest, Maven POM, plugin.xml)
    2. Model classes (I_, X_, M_ via bridge)
    3. Business logic (processes, callouts via generators)
    4. Documentation (README, developer guide)
    5. 2Pack metadata (Application Dictionary XML)
  • Bridge Approach: v1.62.0 uses temporary bridges, full unification in v1.63.0

• app: AI Integration for Application Generator (v1.63.0)

  • AI-Powered Requirements Analysis: RequirementsAnalyzerAI using LangChain4j
    • Natural language requirements → structured application specifications
    • Extracts business entities, attributes, relationships from text
    • Infers required processes, callouts, and validators
    • Suggests iDempiere table structures and naming conventions
    • Methods: analyzeRequirements(), enrichRequirements(), validateRequirements()
  • AI-Powered Schema Design: SchemaDesignerAI using LangChain4j
    • Requirements → optimized iDempiere database schema
    • Designs normalized tables following 1NF, 2NF, 3NF, BCNF
    • Adds standard audit columns automatically (AD_Client_ID, AD_Org_ID, IsActive, etc.)
    • Defines foreign keys, indexes, and constraints
    • PostgreSQL + Oracle compatible
    • Methods: designSchema(), optimizeSchema(), validateSchema(), explainSchema()
  • Quarkus LangChain4j Integration: Leverages existing AI infrastructure (ADR-023)
    • Uses @RegisterAiService for declarative AI services
    • Configurable via application.properties
    • Supports multiple LLM providers (Ollama, Anthropic, OpenAI, Google Gemini)
  • AI Prompts: Expert-level system prompts with iDempiere domain knowledge
    • Database normalization best practices
    • iDempiere naming conventions (XX_ prefix, table structure)
    • Standard columns and access levels
    • Relationship patterns (1:1, 1:N, N:M)
  • Integration: Injected into RequirementsAnalyzerImpl and SchemaDesignerImpl
    • AI-first approach with fallback to basic parsing
    • JSON-based communication between AI and application
    • Ready for production use with configured LLM

[1.60.0] - 2025-12-11

Added

• cli: Hierarchical Command Structure for v1.60 (ADR-050)
  • New Parent Commands: Industry-standard hierarchical grouping (like docker, kubectl, git)
  • Commands:
    • model - Java model class generation (I_, X_, M_ classes)
    • metamodel - Database schema and Application Dictionary management
    • code - Business logic code generation (processes, callouts, events)
    • knowledge - Knowledge base operations (RAG) - aliases: kb, rag
    • db - Database operations (migrations, future: query, analyze)
  • Command Mapping:
    • gen model → model generate
    • dict add table → metamodel create
    • pack out → metamodel export
    • pack in → metamodel import
    • dict sync → metamodel sync
    • gen process → code process
    • gen callout → code callout
    • gen event → code event
    • rag → knowledge (with rag, kb aliases)
    • mig create → db migration create
  • Backward Compatibility: Old commands kept with deprecation warnings (v1.60 → v2.0 migration)
  • See ADR-050 for design rationale

Changed

• BREAKING: Project Rebranding - "iDempiere CLI" → "iDempiere AI Hub" (ADR-049)

  • New Identity: Rebranded as "iDempiere AI Hub" to reflect multi-interface architecture
  • Three Interfaces: CLI, MCP Server, Chat API (formerly "Satellite API")
  • Terminology Changes:
    • "Satellite API" → "Chat API" (more descriptive, less confusing)
    • SatelliteAgent → ChatAgent (class names updated)
    • satellite profile → chat-api profile (Quarkus configuration)
  • Documentation:
    • NEW: docs/VISION.md - Strategic vision, use cases, roadmap
    • NEW: docs/ARCHITECTURE.md - High-level architecture
    • NEW: docs/interfaces/CLI-GUIDE.md - CLI interface guide
    • NEW: docs/interfaces/MCP-GUIDE.md - MCP server guide
    • NEW: docs/interfaces/CHAT-API-GUIDE.md - Chat API guide
    • UPDATED: README.md - Complete rewrite as "iDempiere AI Hub"
  • Repository Name: Unchanged (idempiere-cli) for backward compatibility
  • Maven Artifact: Unchanged (org.cloudempiere:idempiere-cli) for compatibility
  • Rationale: Project has evolved beyond CLI - now unified AI hub with 3 interfaces
  • See ADR-049 for full details

• chat-api: Real Streaming Chat API Implementation (ADR-048)

  • ChatAgent.streamChat(): New streaming method using Multi<String> for real-time token streaming
  • Production Streaming: Replaced placeholder streaming with LangChain4j reactive streaming
  • SSE Support: Server-Sent Events (text/event-stream) with OpenAI-compatible chunk format
  • Features:
    • Real-time token-by-token streaming from LLM (Ollama, Claude, GPT, Bedrock)
    • Token usage tracking during streaming
    • Cost calculation and recording after completion
    • Error handling with proper callbacks
    • Completion marker (data: [DONE]) for client-side stream termination
  • Endpoints:
    • Non-streaming: POST /v1/chat/completions with stream: false
    • Streaming: POST /v1/chat/completions with stream: true
  • Test Script: test-chat-api.sh for comprehensive API testing
  • Documentation: Stateless chat memory decision documented (clients manage conversation history)
  • See Implementation Summary

• rag: K_Entry Content Format Normalization (ADR-040)

  • Converts K_Entry articles to Markdown before embedding for improved RAG search quality
  • EditorJsConverter: Converts Editor.js JSON blocks to clean Markdown
    • Supports: headers, paragraphs, lists, quotes, code, tables, warnings, delimiters
    • Preserves semantic structure while removing JSON noise (no "blocks", "data", "type" in embeddings)
  • HtmlToMarkdownConverter: Converts HTML to Markdown using jsoup
    • Supports: headings, paragraphs, lists, tables, blockquotes, code blocks, emphasis, links
    • Handles nested content and complex HTML structures
  • Three content formats supported:
    • BLK (Editor.js) → Markdown
    • HTM (HTML) → Markdown
    • GFM (Markdown) → Pass-through
  • Benefits:
    • Unified Markdown format improves embedding quality
    • No JSON structure noise in search results
    • Preserves semantic structure (headings, lists, emphasis)
    • AI-friendly representation for better retrieval
  • Configuration: idempiere.cli.rag.k-entry.convert-to-markdown=true (default)
  • Metadata: Added original_format to track source format for debugging
  • Fallback: Uses raw content if conversion fails
  • See ADR-040

• chat-api: Chat API Service - OpenAI-compatible AI backend for iDempiere ERP

  • Architecture (ADR-047): Hybrid REST + Direct SQL integration with iDempiere
  • 11 AI Tools implemented using LangChain4j @Tool annotations:
    • searchRecords(): Search iDempiere tables with OData filters (RestDataToolLogic)
    • getRecord(): Get single record by ID (GeneratedOpenApiFactory)
    • listProcesses(): List available processes and reports (RestDataToolLogic)
    • executeProcess(): Execute business processes with parameters (GeneratedOpenApiFactory)
    • listServerJobs(): List background server jobs (RestDataToolLogic)
    • getServerJob(): Get job details and logs (RestDataToolLogic)
    • toggleServerJob(): Enable/disable jobs (RestDataToolLogic)
    • searchKnowledge(): Search documentation and KB (RagService)
    • executeQuery(): Direct SQL queries (read-only PostgreSQL)
    • checkHealth(): Health status check (RestDataToolLogic)
    • getBackendStatus(): Backend availability status (RestDataToolLogic)
  • ChatToolProvider: Facade pattern reusing existing infrastructure (no duplication)
  • DatabaseQueryTool: Direct PostgreSQL access with SQL validation (SELECT only)
  • ChatAgent: Quarkus LangChain4j @RegisterAiService with auto-wired tools
  • Configuration: Chat API profile, PostgreSQL datasource, guardrails, metrics
  • Reuse Strategy: Leverages ADR-015 (RestDataToolLogic), ADR-009 (OpenAPI client), ADR-021 (RAG)
  • Security: Read-only SQL, client filtering, sensitive data exclusion
  • See ADR-047
  • See Chat API Architecture Summary
  • See Implementation Roadmap

• docs: ADR-039 Code-to-Knowledge Extraction for Consultant Use

  • Enables consultants to understand iDempiere behavior without reading code
  • Answers questions like "Why can't I change the quantity?" in business language
  • Extracts validation rules, calculations, and triggers from Java and SQL layers
  • Identifies enforcement levels: UI-only rules vs database-enforced constraints
  • Generates knowledge bases from templates: functional specs, FAQs, training guides
  • Supports customer support, consultant training, and implementation documentation
  • CLI: knowledge ask "question", knowledge generate --template support-faq

• docs: ADR-038 AI-Assisted AD Documentation Workflow

  • Improves iDempiere Application Dictionary descriptions using AI analysis
  • Finds missing/incomplete Name, Description, Help texts across AD components
  • Generates suggestions following iDempiere writing conventions
  • Uses iDempiere's built-in approval workflow (AD_CtxHelpSuggestion) for review
  • Produces migration scripts for approved documentation improvements

• gen model: Enhanced model generation with full iDempiere core delegation

  • Full delegation: Uses ModelInterfaceGenerator from iDempiere core for all generation logic
  • Type mapping: ModelInterfaceGenerator.getClass() + getDataTypeName() (supports all 60+ DisplayTypes)
  • FK model getters: ModelInterfaceGenerator.isGenerateModelGetter() (generates getC_Order() → I_C_Order)
  • Setter exclusions: ModelInterfaceGenerator.isGenerateSetter() (excludes AD_Client_ID, Created, CreatedBy, Updated, UpdatedBy)
  • Field naming: ModelInterfaceGenerator.getFieldName() (strips _ID suffix, handles _ID_To)
  • Correct handling of special columns: Posted, Processed, Processing, Record_ID
  • Supports: TableDir, Search, Location, Locator, Account, PAttribute references
  • Version-sensitive: Compile-time binding via Maven profiles (-Pv11, -Pv12, -Pv13)
  • v12+ DisplayTypes: UUID, TableUU, SearchUU, JSON, RecordID, TimestampWithTimeZone
  • See ADR-001 Model Generator Type Mapping
  • See ModelInterfaceGenerator

• rag: MediaWiki API integration for smart wiki ingestion

  • MediaWikiClient: Client for querying MediaWiki API (page discovery, timestamps)
  • Auto-discovery of pages via categories (Developer, New_Features)
  • Incremental updates: skip unchanged pages based on revision timestamps
  • Session-scoped cache for efficient re-ingestion
  • Retry with exponential backoff (3 attempts)
  • Fixed 404 errors for default wiki pages (Application_Dictionary, 2Pack, Security)

• rag: Expanded AD metadata ingestion for complete help coverage

  • Added AD_Tab ingestion: tab-level help within windows
  • Added AD_Field ingestion: context-specific field help (DISTINCT by columnname)
  • Disabled AD_Element ingestion (AD_Field provides better context)
  • Multi-language support: ad-metadata.languages=en_US,de_DE
  • Uses iDempiere _Trl tables with COALESCE fallback pattern
  • Language metadata added to embeddings for filtering

• rag: Preflight checks for knowledge ingestion

  • checkEmbeddingModel(): Verifies Ollama/LLM service is reachable
  • checkVectorDatabase(): Verifies pgvector store is available
  • checkRagPrerequisites(): Combined check for both services
  • New error codes: LLM_UNAVAILABLE, EMBEDDING_MODEL_UNAVAILABLE, RAG_VECTORDB_UNAVAILABLE
  • --skip-preflight option to bypass checks (not recommended)
  • Actionable error messages with suggestions (start Ollama, pull model, etc.)

• ai: AWS Bedrock integration for managed LLM and embedding services (ADR-037)

  • Added quarkus-langchain4j-bedrock dependency for AWS Bedrock support
  • Configure via quarkus.langchain4j.chat-model.provider=bedrock
  • Supports Claude 3 (Sonnet, Haiku), Amazon Titan, Nova, Llama via Bedrock
  • Embedding support with Amazon Titan Embed Text V2 (dimension: 1024)
  • AWS credentials via default credential chain (env vars, ~/.aws/credentials, IAM role)
  • See ADR-037 for full configuration details
  • Note: Amazon S3 Vectors deferred pending LangChain4j support

Changed

• config: Renamed environment variables for clarity (breaking change)

  • VECTOR_DB_* → RAG_VECTORDB_PG_* for RAG vector database
  • QUARKUS_DATASOURCE_* → IDEMPIERE_DB_* for iDempiere database
  • The "PG" suffix in RAG_VECTORDB_PG_* clarifies this is PostgreSQL with pgvector
  • Dual database architecture now clearly separated:
    • IDEMPIERE_DB_HOST, IDEMPIERE_DB_PORT, IDEMPIERE_DB_NAME, IDEMPIERE_DB_USER, IDEMPIERE_DB_PASSWORD
    • RAG_VECTORDB_PG_HOST, RAG_VECTORDB_PG_PORT, RAG_VECTORDB_PG_NAME, RAG_VECTORDB_PG_USER, RAG_VECTORDB_PG_PASSWORD
  • Updated ADRs: 005, 010, 016, 021, 022, 023, 028
  • Error code renamed: VECTOR_DB_UNAVAILABLE → RAG_VECTORDB_UNAVAILABLE

• mcp: Added profile validation to MCP server command

  • Checks if mcp profile is active (required for port 8765)
  • Returns exit code 1 with clear instructions if profile is missing
  • Prevents silent failures where server uses random ephemeral port

• registry: Fixed translation table joins for tables without all columns

  • ad_table_trl only has name column (not description/help)
  • Queries now correctly reference only columns that exist in _Trl tables
  • Added TranslationHelper utility for safe COALESCE expressions
  • Rule: Check AD_Column.IsTranslated='Y' to determine _Trl columns

• error-handling: Refactored CliErrorCode enum to include sample messages and suggestions

  • Added sampleMessageTemplate field for format strings
  • Added suggestion field for default resolution suggestions
  • Added getSampleMessage() method for demo messages
  • Removed duplicate switch statements from ErrorDemoCommand

• env: Database restore command (env restore) for DevOps workflows

  • EnvRestoreService: Service for database restore operations
  • S3BackupService: Download backups from AWS S3 buckets
  • DockerPostgresService: Docker container lifecycle management
  • Restores from gzip-compressed PostgreSQL dumps (.gz, .sql, .dump)
  • AWS S3 support: --s3-bucket, --s3-key, --s3-prefix options
  • Docker mode (recommended): --docker creates isolated PostgreSQL containers
  • PostgreSQL version mapping by iDempiere version (v13→PG16, v12→PG15, v11→PG14, v10→PG13)
  • --pg-version option for explicit PostgreSQL version selection
  • --idempiere-version option for automatic PostgreSQL version mapping
  • --docker-port option for custom port mapping (default: 5432)
  • Creates required PostgreSQL roles (adempiere, pg1x33, clde_appserver_user)
  • Terminates existing connections before drop/recreate
  • Creates PostgreSQL extensions (uuid-ossp, pgcrypto, pg_trgm, vector)
  • Applies development environment alterations (disable email, schedulers)
  • --dry-run mode to preview restore plan without executing
  • --backup-dir option to use latest backup from directory

Dependencies

• quarkus-amazon-s3: Added Quarkus Amazon S3 extension for S3 backup downloads
• quarkus-langchain4j-bedrock: Added AWS Bedrock LLM/embedding provider support

[1.56.0] - 2025-12-07

Added

• wizard: Terraform-style wizard flow framework for interactive operations
  • WizardFlow: COLLECT → PLAN → SUMMARIZE → APPLY pattern with type-safe steps
  • JLinePrompt: Arrow-key navigation for menus and checkboxes using JLine3
  • AIDescriptionService: AI-powered generation of iDempiere AD element texts
  • ExecutionPlan: Plan preview with ResourceChange tracking (ADD, UPDATE, DELETE)
  • TableDefinitionYaml: YAML-based table definitions for declarative table creation
  • AITestCommand: Test command for AI description generation (ai-test)
  • TableWizardCommand: Interactive table creation wizard scaffold (dict add table --wizard)

Dependencies

• jline3: Added JLine 3.26.3 for terminal UI with arrow-key navigation

[1.55.0] - 2025-12-07

Added

• error-handling: Structured error handling following clig.dev guidelines (ADR-028)
  • ExitCodes: Standard exit codes (0=success, 1=error, 2=usage, 3=connection, 4=partial)
  • CliErrorCode: Error code enum with iDempiere wiki documentation links
  • CliError: Structured error record with context, suggestions, and documentation
  • PreFlightResult: Pre-flight validation result wrapper
  • PreFlightService: Database state validation before apply operations
  • Human-readable and JSON output formats for errors
  • error-demo command for testing error scenarios

Documentation

• docs: ADR-028 CLI Error Handling and Exit Codes
• docs: ADR-029 AI-Powered Plan Mode (Vibe Mode) for consultants

[1.54.0] - 2025-12-07

Added

• server: REST API server mode (server api) for HTTP access to CLI tools (ADR-026)
  • All shared tool logic exposed via REST endpoints
  • Health check at /api/health
  • Registry endpoints: /api/registry/tables, /api/registry/windows, etc.
  • Query endpoints: /api/query/execute, /api/query/explain
  • Doctor endpoints: /api/doctor/environment, /api/doctor/database
  • Generator endpoints: /api/generator/list, /api/generator/{name}
  • Knowledge endpoints: /api/knowledge/search, /api/knowledge/statistics
  • OpenAPI spec at /q/openapi.yaml and /q/openapi.json
  • Swagger UI at /q/swagger-ui/
• shell: Interactive shell mode (shell) for REPL-style CLI usage (ADR-026)
  • Execute multiple commands without restarting
  • Unknown command rejection with helpful error messages
  • Built-in help, clear screen, and exit commands
• config: Swagger UI always included in builds for API documentation

Documentation

• docs: ADR-026: CLI Execution Modes (shell, API server)
• docs: ADR-027: Implementation Validation

[1.53.0] - 2025-12-07

Added

• ai: LangChain4j observability with --trace flag (ADR-025)
  • TraceContext: Thread-local state for trace collection
  • TraceEvent: Sealed interface with LlmRequest, LlmResponse, ToolCall, ToolResult events
  • CliChatModelListener: CDI observer for Quarkus LangChain4j audit events
  • TraceFormatter: Text and JSON output formatters
  • ask --trace: Show LLM calls, tool executions, token usage, and timing
  • ask --trace-format=json: Machine-readable trace output

Documentation

• docs: ADR-025 LangChain4j Observability and Trace Support

Usage

# Text output (default)
idempiere-cli ask --trace "list all C_ tables"

# JSON output
idempiere-cli ask --trace --trace-format=json "how many orders"

[1.52.0] - 2025-12-07

Added

• ai: Shared ADContextService for enriching AI tool responses with Application Dictionary context
  • Fetches table/window/process metadata with translation support (_Trl tables)
  • Extracts table names from SQL queries automatically
  • Provides hints based on table prefixes (C_, M_, AD_, GL_, XX_)
• ai: LanguageDetector for multilingual support in AI tools
  • Detects user language from query text
  • Supports: de_DE, es_MX, fr_FR, it_IT, pt_BR, nl_NL, ru_RU, ja_JP, zh_CN
  • Returns AD_Language codes for translation table lookups
• registry: Hybrid RAG-augmented search for AD metadata
  • Combines vector similarity search with keyword matching
  • Returns contextual results from wiki and internal KB
• registry: Enhanced describeTable with window/tab context
  • Shows related windows and tabs for each table
  • Includes access level descriptions

[1.51.0] - 2025-12-07

Changed

• ai: Migrated from plain LangChain4j to Quarkus LangChain4j (ADR-023)
  • Chat models now configured via quarkus.langchain4j.ollama.* or quarkus.langchain4j.anthropic.*
  • Embedding models and PGVector store auto-configured by Quarkus CDI
  • CliRouterAgent now uses @RegisterAiService annotation for declarative AI services
  • Simplified AskCommand - agent is now CDI-injected instead of manually built
  • Reduced boilerplate in EmbeddingModelProvider and EmbeddingStoreProvider

Added

• docs: ADR-022: Shared Embedding Infrastructure for multi-client RAG
• docs: ADR-023: Quarkus LangChain4j Migration Plan

Dependencies

• Added io.quarkiverse.langchain4j:quarkus-langchain4j-core:1.3.1
• Added io.quarkiverse.langchain4j:quarkus-langchain4j-ollama:1.3.1
• Added io.quarkiverse.langchain4j:quarkus-langchain4j-anthropic:1.3.1
• Added io.quarkiverse.langchain4j:quarkus-langchain4j-openai:1.3.1
• Added io.quarkiverse.langchain4j:quarkus-langchain4j-pgvector:1.3.1
• Removed plain dev.langchain4j:langchain4j-* (replaced by Quarkus extensions)
• Updated dev.langchain4j:langchain4j-document-parser-apache-tika to 1.6.0-beta12

Configuration

• New Quarkus LangChain4j properties:
  • quarkus.langchain4j.chat-model.provider - Select chat model provider (ollama, anthropic, openai)
  • quarkus.langchain4j.embedding-model.provider - Select embedding model provider
  • quarkus.langchain4j.ollama.chat-model.model-id - Ollama chat model
  • quarkus.langchain4j.ollama.embedding-model.model-id - Ollama embedding model
  • quarkus.langchain4j.anthropic.api-key - Anthropic API key
  • quarkus.langchain4j.pgvector.datasource - Named datasource for vector store
  • quarkus.langchain4j.pgvector.table - Embeddings table name
  • quarkus.langchain4j.pgvector.dimension - Vector dimensions
• Removed obsolete idempiere.cli.rag.embedding.model (now framework-managed)
• Removed obsolete idempiere.cli.rag.vector-db.* (now quarkus.datasource.vector.*)

[1.50.0] - 2025-12-07

Added

• rag: RAG (Retrieval-Augmented Generation) architecture for knowledge-augmented AI (ADR-021)

  • New knowledge command (aliases: kb, rag) for knowledge base management
  • Subcommands: init, ingest, search, status, clear, validate
  • init command auto-creates pgvector extension and embeddings table
  • PGVector integration for vector embeddings storage
  • Local embedding model (bge-small-en-q, 384 dimensions) - zero API costs
  • Three knowledge sources:
    • iDempiere Wiki documentation
    • CloudEmpiere K_Entry articles (AD_Client_ID=1000014)
    • Application Dictionary metadata (tables, windows, processes, elements)

• ai: RAG tools integrated with ask command

  • searchKnowledge - Semantic search across all knowledge sources
  • findADEntity - Look up specific AD tables/windows/processes
  • lookupDevelopmentDocs - Find development documentation
  • getKnowledgeStats - Get knowledge base statistics

Configuration

• New RAG configuration properties in application.properties:
  • idempiere.cli.rag.embedding.* - Embedding store settings
  • idempiere.cli.rag.vector-db.* - Optional separate vector database
  • idempiere.cli.rag.wiki.* - Wiki ingestion settings
  • idempiere.cli.rag.k-entry.* - K_Entry ingestion settings
  • idempiere.cli.rag.ad-metadata.* - AD metadata ingestion
  • idempiere.cli.rag.retrieval.* - Search settings

Dependencies

• langchain4j-pgvector - PostgreSQL vector store
• langchain4j-embeddings-bge-small-en-q - Local ONNX embedding model
• langchain4j-document-parser-apache-tika - HTML/document parsing
• langchain4j-easy-rag - RAG utilities

Fixed

• mcp: Fixed MCP server command registration
  • Changed command name from mcp-server to mcp for consistency with documentation
  • Removed hidden = true flag to make command visible in help
  • Fixed command name collision: renamed nested server command to rest
  • Removed duplicate top-level MCP command registration
  • Usage: idempiere-cli server mcp starts MCP server for AI assistants

Documentation

• adr-021: RAG Architecture for Knowledge-Augmented AI Assistance

[1.32.0] - 2025-12-07

Added

• cli: New --help-all flag shows full command tree with all subcommands expanded
  • Displays categorized commands: Development, Application Dictionary, Server & AI, DevOps, Utility
  • Shows tree structure with descriptions for every subcommand

Enhanced

• cli: Parent commands now show detailed subcommand help with --help flag
  • All 9 parent commands (dev, dict, gen, pack, ide, env, server, ai, util) include footer with subcommands and examples
  • Fixed picocli % format escape issue in dict command examples

[1.31.0] - 2025-12-07

Added

• cli: New grouped command structure (ADR-019)
  • dev - Development environment: init, doctor, setup, config
  • dict - Application Dictionary: add, sync, registry, generate, translation
  • gen - Code generation: model, callout, process, event, ai
  • pack - PackOut operations: out, in, validate, migration
  • ide - IDE configuration: eclipse, intellij, vscode
  • env - Environment management: backup, restore, deploy, clone, status
  • server - Server management: cache, jobs, workflow, mcp
  • ai - AI features: ask, generate, models, providers
  • util - Utilities: batch, watch, plugin
• cli: ASCII banner and tree-structured help display (kubectl-style)
• cli: Updated branding: "iDempiere Development, AI & DevOps CLI"

Changed

• cli: Commands reorganized into logical groups for better discoverability
• cli: Legacy commands kept for backward compatibility (hidden from help)

Documentation

• adr-019: CLI Command Structure Redesign
  • Prefix-based command grouping
  • AI/LLM native understanding with MCP tool naming conventions
  • CLI-to-MCP tool mapping (snake_case for MCP tools)

[1.30.0] - 2025-12-07

Added

• mcp: New mcp-server command to start MCP server for AI assistants
  • Keeps server running for Claude Code/Desktop connections
  • HTTP/SSE endpoints on port 8765
  • Usage: java -Dquarkus.profile=mcp -jar idempiere-cli.jar mcp-server

Changed

• deps: Upgrade Quarkus from 3.16.3 to 3.27.1 for MCP Server compatibility
• mcp: Switch from quarkus-mcp-server-stdio to quarkus-mcp-server-http
  • Avoids stdout conflict with Picocli
  • Enables HTTP/SSE transport for remote AI assistants
• services: Make database injection optional via Instance<DataSource>
  • PackOutService, PackInValidationService, CoreProcessService, MigrationScriptService
  • CLI commands gracefully handle missing database configuration

Fixed

• mcp: Fix NoSuchMethodError: LaunchMode.isProduction() by upgrading Quarkus
• mcp: Add CORS configuration for MCP profile

Documentation

• adr-010: Update for HTTP transport, add mcp-server command usage

[1.29.0] - 2025-12-06

Added

• ai: LangChain4j integration for natural language CLI routing (ADR-013)

  • New ask command for natural language interface to CLI
  • Multi-provider support: Ollama (local), Claude, Gemini, OpenAI
  • Tool-based architecture with @Tool annotations
  • See: ADR-013

• ai: SQL query support via ask command

  • Natural language to SQL translation
  • Read-only SELECT queries only (security)
  • Row limits and query timeouts enforced
  • Sensitive columns masked (passwords, tokens)
  • Query templates for common iDempiere patterns

• ai: Shared tool logic layer for AI integrations

  • RegistryToolLogic - AD metadata queries
  • TableToolLogic - Table operations
  • GeneratorToolLogic - Code generation
  • DoctorToolLogic - Diagnostics
  • QueryToolLogic - SQL query execution
  • Reusable by LangChain4j and future MCP Server (ADR-010)

• deps: LangChain4j dependencies (v0.36.2)

  • langchain4j - Core framework
  • langchain4j-ollama - Local LLM support
  • langchain4j-anthropic - Claude API
  • langchain4j-google-ai-gemini - Gemini API
  • langchain4j-open-ai - OpenAI API

Usage Examples

# Application Dictionary queries
idempiere-cli ask --provider=claude "list all order tables"
idempiere-cli ask --provider=claude "describe the C_Order table"

# SQL queries (natural language)
idempiere-cli ask --provider=claude "how many orders this month"
idempiere-cli ask --provider=claude "top 10 customers by revenue"

# Code generation
idempiere-cli ask --provider=claude "generate a model for M_Product"

[1.28.0] - 2025-12-06

Changed

• cli: Rename migration command to migration-script for consistency

  • MigrationCommand → MigrationScriptCommand
  • MigrationService → MigrationScriptService
  • MigrationToolLogic → MigrationScriptToolLogic
  • Command name: migration → migration-script

• migration-script: Extend support to all AD element types

  • table - AD_Table + AD_Column + CREATE TABLE DDL
  • column - AD_Column + ALTER TABLE DDL
  • window - AD_Window + AD_Tab + AD_Field
  • process - AD_Process + AD_Process_Para
  • reference - AD_Reference + AD_Ref_List/AD_Ref_Table
  • menu - AD_Menu + AD_TreeNodeMM
  • message - AD_Message
  • sysconfig - AD_SysConfig

• migration-script: Version-compatible SQL queries

  • Queries use only columns available in iDempiere v10-v13
  • Removed version-specific columns (e.g., tableidsequence)

Added

• docs: Document local migration folder (migration-local/) for partner scripts
  • Partners use migration-local/ with local IDs (MAX+1)
  • Core uses migration/ with centralized IDs (JIRA)
  • Updated ADR-005

1.27.1 - 2025-12-06

Changed

• services: Rename TwoPackValidationService to PackInValidationService
  • Refactored to use PackIn-style SAX parsing (mirrors PackIn.importXML())
  • Added PackInValidationHandler mimicking iDempiere's PackInHandler
  • Added required fields validation per PIPO2 ElementHandler
  • Added dependency analysis (AD_Tab→AD_Table, AD_Field→AD_Column)
  • This is like a "PackIn test" - validates 2Pack without importing

1.27.0 - 2025-12-06

Added

• api: OpenAPI-generated REST client integration (ADR-009 Complete)

  • GeneratedOpenApiFactory - Factory for OpenAPI-generated API clients
  • Auto-configured with iDempiere credentials from IdempiereConfig
  • Full type-safe access to all 21 iDempiere REST API categories
  • See: ADR-009

• cli: New cache command for iDempiere server cache management

  • cache list - List all caches and statistics
  • cache reset <name> - Reset specific cache by name
  • cache reset-all - Reset all caches
  • Uses generated CachesApi for type-safe REST calls

• cli: New server command for iDempiere server management

  • server nodes - List server nodes in cluster
  • server jobs - List server jobs
  • server health - Check server health status
  • Uses generated NodesApi, ServerJobsApi, HealthApi

• cli: New workflow command for workflow activity management

  • workflow list - List pending workflow activities
  • workflow approve <id> - Approve workflow activity
  • workflow reject <id> - Reject workflow activity with reason
  • workflow forward <id> - Forward activity to another user
  • Uses generated WorkflowsApi

• services: ADService facade architecture for unified AD operations

  • ADService interface - Unified facade for Application Dictionary
  • RestADService - REST API implementation
  • SqlADService - SQL migration script output
  • PackOutADService - 2Pack XML export output
  • Enables single operation → multiple output formats
  • See: ADR-012

Changed

• api: Commands updated to use GeneratedOpenApiFactory for REST calls
• docs: ADR status updates - 9 of 11 ADRs now implemented

1.26.0 - 2025-12-06

Added

• migration: Complete migration script management for plugin development
  • migration init - Initialize migration folder structure (iX.Xz/ + processes_post_migration/)
  • migration generate table - Generate paired PostgreSQL/Oracle migration scripts for tables
  • migration generate column - Generate migration scripts for columns
  • migration apply - Apply migration scripts via database connection
  • migration apply-post - Apply post-migration scripts (data sync, translations, etc.)
  • Uses PostgreSQL register_migration_script() function for automatic registration
  • Function handles: ad_migrationscript insert, AD_System.LastMigrationScriptApplied update, idempotency
  • Follows iDempiere naming convention: YYYYMMDDHHMM_ISSUE-XXX.sql
  • Uses DdlGenerator (mirrors MColumn.getSQLAdd/MTable.getSQLCreate patterns)
  • Supports --dry-run for previewing changes
  • Supports --postgresql-only / --oracle-only for single-dialect generation
  • See: Migration Guide
  • See: ADR-005
  • Implementation Note: Generates SQL from AD metadata (not SQL interception like core iDempiere)
  • For Core Contributions: Use iDempiere's native "Log Migration Script" preference instead
  • Missing: Window/Process/Reference migration generation (planned)

1.25.0 - 2025-12-01

Added

• init: Project governance templates for scaffolded plugins

  • Init command now generates CHANGELOG.md with Keep a Changelog format
  • Init command now generates CONTRIBUTING.md with commit conventions and workflow
  • New GOVERNANCE.md documentation for project governance structure
  • PluginScaffoldConfig.getGeneratedDate() for template date rendering
  • See: GOVERNANCE.md

• translation: Translation command for AD element translations (planned)

  • TranslationCommand and TranslationService scaffolding
  • See: Translation Guide

• docs: Architecture Decision Records

  • ADR-010: MCP Server Architecture for AI integration
  • ADR-011: CloudEmpiere AI Integration strategy
  • Project templates for repository bootstrapping

1.24.0 - 2025-12-01

Added

• 2pack: 2Pack generation, validation, and import commands for PackOut/PackIn files
  • 2pack generate - Generate 2Pack from AD elements in database
    • Export tables with columns (--table)
    • Export windows with tabs and fields (--window)
    • Export processes with parameters (--process)
    • Export menus (--menu)
    • Export references with list/table values (--reference)
    • Output to ZIP or XML (--xml-only)
    • Auto-validate with --validate flag
    • Dry-run mode with --dry-run
    • Compatible with META-INF/2Pack.zip for plugin auto-deployment
  • 2pack validate <file> - Validate 2Pack file (ZIP or XML)
    • XML structure validation (well-formed XML, required elements)
    • Element type validation (known PIPO2 element handlers)
    • Required field validation for AD_Table, AD_Column, AD_Window, AD_Process
    • UUID reference validation against database (--check-db)
    • Dependency analysis (checks for referenced elements in pack)
    • Supports both .zip and .xml file formats
    • JSON output support with --output-json flag
  • 2pack packin <file> - Import 2Pack via REST API
    • Creates AD_Package_Imp record
    • Uploads 2Pack as attachment via Uploads API
    • Triggers PackIn processing
    • Supports --validate flag to validate before import
    • Supports --dry-run to preview REST API steps
  • Implementation based on iDempiere PIPO2 element handlers
  • See: 2Pack Guide
  • See: https://wiki.idempiere.org/en/Developing_Plug-Ins_-2Pack-_Pack_In/Out

1.23.0 - 2025-11-30

Added

• registry: Application Dictionary registry command for direct database access
  • registry - Show AD element statistics (tables, columns, windows, processes, references)
  • registry tables [--filter PATTERN] [--custom] [--limit N] - List AD tables
  • registry windows [--filter PATTERN] [--limit N] - List AD windows
  • registry processes [--filter PATTERN] [--limit N] - List AD processes
  • registry references [--filter PATTERN] [--limit N] - List AD references
  • registry columns <table> - List columns for a specific table
  • registry table <name> - Get detailed table information
  • registry export [category] --output <dir> - Export AD to JSON for AI/MCP
    • Exports: references, display-types, tables, windows, processes, patterns, elements
    • Includes List values and Table validations for references
    • Includes columns for each table with full metadata
    • Includes tabs for each window
    • Includes parameters for each process
    • Standard patterns: document, master-data, transaction-line, audit-columns
  • JSON output support with --json flag
  • Implements ADR-008 Application Dictionary Registry architecture

1.22.0 - 2025-11-30

Added

• config: Database connection configuration command (config db)

  • New config db subcommand for PostgreSQL database configuration
  • Supports --host, --port, --name, --user, --password options
  • --test flag to verify database connectivity
  • --show flag to display current configuration
  • Environment-variable-first approach for Docker/Kubernetes:
    • IDEMPIERE_DB_HOST, IDEMPIERE_DB_PORT, IDEMPIERE_DB_NAME
    • IDEMPIERE_DB_USER, IDEMPIERE_DB_PASSWORD
  • iDempiere Docker compatibility: DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASS
  • JSON output support with --json flag
  • Displays PostgreSQL version on successful connection

• test: Comprehensive integration tests for IdempiereApiClient (43 tests)

  • Added WireMock dependency for HTTP mocking
  • Tests for generic HTTP operations (GET, POST, PUT, DELETE)
  • Tests for Health API, Cache API, Workflow API
  • Tests for AD entity operations (Table, Column, Window, Tab, Process, Reference)
  • Tests for connection error handling (401, 403, 404, 503)
  • Tests for OData query parameters ($filter, $select, $orderby, $top, $skip)
  • Tests for process execution and batch operations

1.21.0 - 2025-11-30

Changed

• api: Unified REST client architecture (replaces IdempiereClient + IdempiereRestService)
  • Created single IdempiereApiClient combining all REST operations
  • Created Quarkus-native REST client interfaces:
    • IdempiereModelsApi - OData model operations
    • IdempiereAuthApi - Authentication endpoints
    • IdempiereProcessApi - Process execution
    • IdempiereSystemApi - Health, caches, nodes, forms, tasks
    • IdempiereWorkflowApi - Workflow activities
  • Removed OpenAPI Generator plugin (incomplete spec caused void returns)
  • Removed CXF multipart dependencies (conflicts with Quarkus)
  • Updated all commands to use unified IdempiereApiClient

Removed

• api: IdempiereClient.java - replaced by unified IdempiereApiClient
• api: IdempiereRestService.java - merged into IdempiereApiClient
• build: OpenAPI Generator Maven plugin (manual interfaces preferred)

1.20.0 - 2025-11-30

Added

• build: OpenAPI Generator Maven plugin (Phase 5 Milestone)
  • Added openapi-generator-maven-plugin 7.10.0 for REST client generation
  • Added build-helper-maven-plugin for generated sources integration
  • Configured MicroProfile REST Client generation with Jakarta EE
  • Added MicroProfile REST Client API 3.0.1 dependency
  • Added Jakarta Validation API dependency for generated models
• openapi: Versioned OpenAPI specification directory
  • Created openapi/ directory for versioned specs
  • Added idempiere-openapi-v12.yml - iDempiere 12.x REST API spec
  • Created idempiere-openapi-current.yml symlink for active version
  • Generated 21 API interfaces and 70+ model classes:
    • AuthenticationApi, ModelsApi, ViewsApi, WindowsApi
    • ProcessApi, FormsApi, TasksApi, ReferencesApi
    • FilesApi, CachesApi, NodesApi, ServerJobsApi
    • SchedulersApi, InfoWindowsApi, WorkflowsApi
    • StatusLinesApi, ChartsApi, MenutreeApi
    • UploadsApi, BatchApi, HealthApi
• docs: ADR-009 OpenAPI-Based REST Client for iDempiere
  • Documents plan to generate type-safe REST client from OpenAPI spec
  • Catalogs all 70+ iDempiere REST endpoints across 18 categories
  • Defines OData query parameters ($filter, $select, $expand, etc.)
  • Proposes code generation with Quarkus/MicroProfile integration
  • Includes migration path from hand-written IdempiereClient
  • Added OpenAPI versioning documentation
• docs: ADR-008 Application Dictionary Element Registry
  • Comprehensive registry design for AI/MCP/CLI AD element knowledge
  • Defines static docs, JSON schemas, and dynamic export architecture
  • Documents core AD elements, relationships, and standard patterns
  • Proposes registry CLI command for element lookup and export

1.19.0 - 2025-11-30

Added

• cli: Reference and validation rule management via REST API (Phase 4 Complete)
  • add reference - Create AD_Reference records
    • --type - Reference type: list, table, datatype
    • --values - List values as VALUE=Name pairs (e.g., DR=Draft,CO=Complete)
    • --table - Table name for table references
    • --key-column - Key column for table lookup
    • --display-column - Display column for table lookup
    • --where - Where clause filter for table reference
    • --order-by-value - Order list by value instead of name
    • --dry-run - Preview without creating
  • add ref-list - Add list values to existing references
    • Accepts VALUE=Name format
    • --reference - Target reference name or ID
  • add validation - Create AD_Val_Rule records
    • --code - SQL where clause with @Variable@ context support
    • --type - Rule type: S=SQL, J=Java
    • --dry-run - Preview without creating
• api: New model classes for reference management
  • ADReferenceRecord - AD_Reference table records
  • ADRefList - AD_Ref_List for list values
  • ADRefTable - AD_Ref_Table for table lookup configuration
  • ADValRule - AD_Val_Rule for dynamic validation
• api: Reference CRUD methods in IdempiereClient
  • createReference(), getReference(), getReferenceByName(), getReferenceByNameOrId()
  • getReferencesByPattern(), updateReference()
  • createRefList(), getRefListItems(), getRefListByValue(), updateRefList()
  • createRefTable(), getRefTable(), updateRefTable()
  • createValRule(), getValRule(), getValRuleByName(), getValRuleByNameOrId()
  • getValRulesByPattern(), updateValRule()

1.18.0 - 2025-11-30

Added

• cli: Menu creation via REST API (Phase 3 Complete)
  • add menu - Create AD_Menu entries
    • --window - Link to window by name or ID
    • --process - Link to process by name or ID
    • --report - Link to report process
    • --form - Link to form by ID
    • --folder - Create folder/summary menu
    • --parent - Parent menu for hierarchy positioning
    • --seq - Sequence number (auto if not specified)
    • --dry-run - Preview without creating
• api: New model class ADTreeNodeMM for menu tree positioning
• api: Menu CRUD methods in IdempiereClient
  • updateMenu() - Update AD_Menu
  • getMenusByPattern() - Search menus by name
  • getSummaryMenus() - List folder menus
  • getMenuByNameOrId() - Flexible lookup
  • createTreeNode() - Create tree node for menu positioning
  • getMenuTreeNode() - Get tree node for menu
  • getChildTreeNodes() - Get children in menu tree
  • updateTreeNode() - Reposition menu in tree
  • getNextMenuSeqNo() - Auto-calculate sequence
• api: Window lookup methods in IdempiereClient
  • getWindowByName() - Lookup window by name
  • getWindowByNameOrId() - Flexible lookup

1.17.0 - 2025-11-30

Added

• cli: Process and parameter creation via REST API
  • add ad-process - Create AD_Process records
    • --class - Java class name for process execution
    • --procedure - Database procedure name for SQL processes
    • --jasper - Jasper report path for reports
    • --execution-type - Force background (B) or foreground (F)
    • --server - Server-side only process flag
    • --dry-run - Preview without creating
  • add ad-process-param - Add parameters to processes (AD_Process_Para)
    • --type - Parameter type (string, date, table, etc.)
    • --mandatory - Required parameter flag
    • --range - Enable range input (from/to)
    • --default - Default value with @Variable@ support
    • --display-logic - Conditional visibility
    • --mandatory-logic - Conditional mandatory
    • Auto sequence numbering
• api: New model class ADProcessPara for process parameters
• api: Process CRUD methods in IdempiereClient
  • getProcessByValue() - Lookup by search key
  • getProcessesByPattern() - Search processes
  • createProcess() - Create AD_Process
  • updateProcess() - Update AD_Process
  • getProcessParameters() - List parameters
  • getProcessParameter() - Get parameter by ID
  • getProcessParameterByColumnName() - Get parameter by column name
  • createProcessParameter() - Create AD_Process_Para
  • updateProcessParameter() - Update AD_Process_Para

1.16.0 - 2025-11-30

Added

• docs: Application Dictionary documentation for Phase 2 features
  • WINDOW_CUSTOMIZATION.md - Role-specific window layouts (AD_UserDef_Win)
  • PROCESS_CUSTOMIZATION.md - Role-specific process parameters (AD_Process_Para_Custom)
  • TREE.md - Hierarchical organization with ~17 tree types (AD_Tree)
  • CONTEXT_HELP.md - Contextual help system (AD_CtxHelp)
  • STATUS_LINE.md - Configurable status line and quick info (AD_StatusLine)
  • CHART.md - Dashboard charts and widgets (AD_Chart, PA_DashboardContent)
  • REST_VIEW.md - REST API and custom views
  • Updated README.md hub with all new documentation
  • Added Phase 8 to IMPLEMENTATION_PLAN.md with 7 new features

Changed

• docs: Validated and enhanced PROCESS.md against iDempiere wiki
  • Added ExecutionType (v6.2+), AllowMultipleExecution, FileNamePattern fields
  • Added AD_Process_Para fields: Placeholder, DateRangeOption, MandatoryLogic, IsEncrypted, IsAutocomplete, IsShowNegateButton
  • Added OSGi registration patterns (@Process annotation, factory scanning)
  • Added Scheduler integration (AD_Scheduler, AD_Scheduler_Para, AD_SchedulerRecipient)
  • Updated implementation status for v1.15.0 features
• api: Added ExecutionType, AllowMultipleExecution, FileNamePattern fields to ADProcess model

1.15.0 - 2025-11-30

Added

• cli: Window generation enhancements
  • --attach-process - Attach process to window toolbar (AD_Window.AD_Process_ID)
  • --add-to-menu - Create menu entry for window (AD_Menu)
  • --menu-name - Custom name for menu entry
  • --detail-tab TABLE:PROCESS - Attach process to detail tab toolbar (AD_Tab.AD_Process_ID)
• api: New model classes for window features
  • ADProcess - AD_Process model for process lookup
  • ADMenu - AD_Menu model for menu creation
  • Process ID fields added to ADWindow and ADTab
• docs: Application Dictionary documentation
  • /docs/application-dictionary/ - Central hub for AD components
  • Separate docs for Table, Window, Process, Reference, InfoWindow, Menu
  • iDempiere core class references in all documentation

Changed

• cli: Detail tab format now supports TABLE:PROCESS for attaching processes
• docs: Updated WINDOW.md with implementation status table and core integration notes

Documentation

• docs: Comprehensive audit and planning documentation
  • FUNCTIONAL_COVERAGE_AUDIT.md - 65% coverage assessment against iDempiere
  • IMPLEMENTATION_PLAN.md - 7-phase roadmap to full coverage
  • AUDIT_SYSTEM.md - Systematic audit framework
  • docs/audits/ - Archive for periodic audit snapshots
  • iDempiere version tracking and breaking change log

1.14.0 - 2025-11-30

Added

• build: Native binary support via GraalVM
  • Container-based build for Linux (-Dquarkus.native.container-build=true)
  • Local build for macOS/Windows (requires GraalVM)
  • 68MB executable, instant startup

1.13.0 - 2025-11-30

Added

• cli: generate window command for Window/Tab/Field generation
  • Creates complete UI structure from AD tables
  • Supports window types: Maintain (M), Transaction (T), Query (Q)
  • Auto-generates fields with smart visibility rules
  • --dry-run to preview without creating
  • Custom window/tab names and entity types

1.12.0 - 2025-11-30

Added

• cli: generate model command for X_ and I_ model class generation
  • Generates X_ base classes and I_ interfaces from AD tables
  • Uses iDempiere DisplayType for accurate Java type mapping
  • Supports single tables, multiple tables, or LIKE patterns
  • --interface-only and --class-only options
  • --dry-run to preview files without creating them
  • Configurable package name and output directory

1.11.0 - 2025-11-30

Added

• cli: intellij-config command for IntelliJ IDEA configuration
  • Generates Maven run configurations (Install, Server, Model Generator)
  • Generates OSGi configuration templates (bundles.info, dev.properties)
  • Supports all iDempiere versions (10, 11, 12, 13)
  • --dry-run to preview generated files
• cli: vscode-config command for Visual Studio Code configuration
  • Generates extensions.json with recommended extensions
  • Generates settings.json with Java/Maven configuration
  • Generates launch.json with debug configurations
  • --dry-run to preview generated files

1.10.0 - 2025-11-30

Added

• cli: batch command for executing multiple CLI commands from a file
  • Supports YAML and JSON batch files
  • Variable substitution with ${variable} syntax
  • --continue-on-error to continue even if a command fails
  • --dry-run to preview commands without executing
  • --var name=value to override batch file variables
  • Progress reporting with success/failure summary

1.9.0 - 2025-11-30

Added

• cli: setup-dev-env command to bootstrap iDempiere development environment
  • Checks prerequisites (Java, Maven, Git)
  • Clones iDempiere repository with specified branch
  • Builds iDempiere (mvn verify or mvn validate)
  • Supports release-10, release-11, release-12, development branches
  • --dry-run to preview steps
  • --eclipse-config to generate Eclipse target platform

1.8.0 - 2025-11-30

Added

• cli: eclipse-config command for Eclipse PDE configuration
  • Generates target platform project with .target file
  • Generates launch configuration (.launch) for debugging
  • Auto-detects plugin ID from pom.xml or MANIFEST.MF
  • Supports all iDempiere versions (10, 11, 12, 13)
  • --dry-run to preview generated files

1.7.0 - 2025-11-30

Added

• cli: watch command for file monitoring and auto-rebuild
  • watch plugin - Watch plugin project, rebuild on .java file changes
  • watch export - Watch AD table, re-export on changes
  • Supports custom commands, patterns, debounce delay

1.6.0 - 2025-11-30

Added

• cli: Global --json flag for JSON output mode (M2M/scripting support)
  • doctor --json - Environment check results as JSON
  • config --show --json - Configuration as JSON
  • plugin list --json - Plugin list as JSON
• util: JsonOutput utility class for consistent JSON formatting
• util: OutputContext singleton for tracking output mode

1.5.0 - 2025-11-30

Fixed

• cli: Register missing sync command in CLI subcommands
• cli: Add missing --help option to init and doctor commands (mixinStandardHelpOptions)
• cli: Rename init --version/-v to --plugin-version/-p to avoid conflict with picocli's -V/--version

1.4.0 - 2025-11-30

Added

• build: iDempiere branch-to-dependency mapping in Maven profiles
  • Each profile (v10, v11, v12, v13) now sets correct artifact version
  • Added idempiere.artifact.version property per profile

Changed

• docs: Rewrite README.md as accurate quick-start guide
• docs: Update PROJECT.md with current status and specifications
• docs: Add branch-to-dependency mapping rule to ADR-001 and CLAUDE.md

1.3.0 - 2025-11-30

Added

• deps: iDempiere 13.0.0-SNAPSHOT integration with core classes (MTable, MColumn, DisplayType)
• deps: Maven profiles for iDempiere versions (v11, v12, v13)
• services: Direct DB access via JDBC + Quarkus Agroal connection pooling

Fixed

• config: Config file path conflict - changed to ~/.idempiere-cli/config.properties
• api: URL encoding for REST API OData $filter parameters
• api: Detailed HTTP error messages (401/403/404/connection errors)
• cli: Disable HTTP server for CLI mode (quarkus.http.port=0)

Changed

• refactor: Use iDempiere core classes in generators (MTable, MColumn)

1.2.0 - 2025-11-28

Added

• generator: Virtual File System (GeneratorTree) - ADR-003 Phase 1

  • Stage file changes in memory before applying
  • Atomic commits with rollback on failure
  • Preview changes with --dry-run

• generator: Composable Generators - ADR-003 Phase 3

  • Generator interface for modular code generation
  • Individual generators: Init, PluginStructure, Callout, EventHandler, Process, ZkForm, Report, ModelClass

• generator: Schema-Driven Validation - ADR-003 Phase 2

  • JSON schema files for all generators
  • x-prompt extension for interactive input

• generator: Interactive Prompts - ADR-003 Phase 5

  • InteractivePrompt service for user input
  • --interactive flag for InitCommand

• generator: AST Manipulation - ADR-003 Phase 4

  • JavaAstModifier using JavaParser
  • Add imports, annotations, methods, fields

• table: Enhanced Table Creation - ADR-004

  • Column templates (standard, document, accounting, import)
  • Window/Tab/Field generation
  • Multiple output formats (REST, SQL, 2Pack)
  • Import table support (--import, --target-table)

• sync: Sync command with table and column subcommands

• export: Export command for 2Pack XML and SQL generation

Changed

• refactor: Architectural cleanup

  • Renamed model.PluginConfig to PluginScaffoldConfig
  • Moved table/output services to services/ package
  • Clear separation: generators (file staging) vs services (API)

• refactor: Align DdlGenerator with iDempiere source patterns

  • DisplayType constants matching iDempiere
  • YesNo CHECK constraint per MColumn.getSQLDDL()

Documentation

• ADR-003: Generator Architecture (Nx-patterns)
• ADR-004: Enhanced Table Creation
• ADR-005: iDempiere Migration Script Architecture
• ADR-006: CLI as M2M API

1.1.0 - 2025-11-20

Added

• plugin: Plugin architecture for CLI extensibility

  • Plugin SPI: PluginProvider, CommandProvider, GeneratorProvider, AIProvider
  • Plugin loader with ServiceLoader and JAR discovery
  • YAML configuration (~/.idempiere-cli/config.yaml)
  • plugin command: list, install, remove, info, init-config

• ai: AI-powered code generation

  • AIService abstraction
  • ClaudeProvider for Anthropic Claude API
  • ai command: generate, models, providers

• cli: Add extension commands

  • add callout - Add callout to existing plugin
  • add process - Add process to existing plugin
  • add event-handler - Add event handler to existing plugin

Changed

• cli: Rename cloudempiere version to custom for generic fork support
• ADReference: Version-specific field types with validation
  • JSON (v11+), UUID (v13+), Chart, Dashboard, Timezone
  • isAvailable(version) validation

Documentation

• ADR-001: iDempiere Version Compatibility Strategy
• ADR-002: CLI Plugin Architecture
• FEATURES.md: Feature matrix and version tracking
• USER_GUIDE.md: Comprehensive usage documentation

1.0.0 - 2025-11-01

Added

• cli: Initial release

  • doctor - Validate development environment
  • init - Scaffold OSGi plugins
  • config - Configure REST API connection
  • add table - Create AD tables
  • add column - Add columns to tables

• core: Quarkus 3.16 + Picocli framework

• templates: Qute template engine for code generation

• api: iDempiere REST API client

Supported

• iDempiere versions: 10, 11, 12, 13, Custom Fork
• Java 17 (Java 21 for v13)
• Extensions: Callout, EventHandler, Process, ZkForm, Report, ModelClass