ApiLogicServer 15.2.3__py3-none-any.whl → 15.2.10__py3-none-any.whl

api_logic_server_cli/api_logic_server.py

@@ -12,9 +12,11 @@ ApiLogicServer CLI: given a database url, create [and run] customizable ApiLogic
 Called from api_logic_server_cli.py, by instantiating the ProjectRun object.
 '''
 
-__version__ = "15.02.03"  # last public release: 15.02.00
+__version__ = "15.02.10"  # last public release: 15.02.07
 recent_changes = \
     f'\n\nRecent Changes:\n' +\
+    "\t10/28/2025 - 15.02.10: Tutor 3.3 (working, vibe transtion) \n"\
+    "\t10/26/2025 - 15.02.07: Clarify order created for ship test, security fixes [105], tutor 2.1 \n"\
     "\t10/22/2025 - 15.02.03: Copilot test creation from rules and custom APIs with issues [103, 104] \n"\
     "\t10/06/2025 - 15.01.06: Incorrect dbml reln arrows [102] \n"\
     "\t09/27/2025 - 15.01.05: Error reporting for bad test data rebuild [101], Minor fix to ensure react-app cards have links \n"\

api_logic_server_cli/prototypes/base/.github/.copilot-instructions.md

@@ -1,11 +1,54 @@
+---
+title: Copilot Instructions for GenAI-Logic Projects
+Description: Project-level instructions for working with generated projects
+Source: ApiLogicServer-src/prototypes/base/.github/.copilot-instructions.md
+Propagation: CLI create command → created projects (non-basic_demo)
+Usage: AI assistants read this when user opens any created project
+version: 2.1
+changelog:
+  - 2.1 (Oct 2025) - Streamlined OBX for non-tutorial projects, friendly collaborative tone
+  - 2.0 (Oct 2025) - Added front matter, updated for OBX improvements
+  - 1.0 (Initial) - Comprehensive technical reference
+---
+
+# GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
 
+⚠️ **IMPORTANT FOR AI ASSISTANTS**: When user first opens this project or asks you to read instructions, present the Welcome section below directly to the user. Do not explain that you're following instructions - just present the welcome message naturally. The technical reference sections after the welcome are for later consultation only.
 
+---
 
-# GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
+## Welcome
+
+**Welcome! I'm here to help with your GenAI-Logic project.**
+
+This is a complete, working microservice auto-generated from your database schema.
+
+**What's already built:**
+- **Admin Web Application** - Live at `http://localhost:5656`
+- **REST API Endpoints** - All database tables exposed at `/api/*`
+- **Database Models** - Complete SQLAlchemy ORM in `database/models.py`
+- **Authentication System** - JWT-based auth framework
+- **Business Logic Engine** - Declarative rules system
+
+---
 
-## Project Type: Auto-Generated Microservice
+**Here are some things I can help you with:**
 
-This is a **GenAI-Logic (aka API Logic Server) project** - a complete, working microservice - auto-generated from a database schema.
+1. **Add business logic** - Describe your requirements in natural language, I'll generate declarative rules
+2. **Customize the API** - Add custom endpoints for your specific needs
+3. **Create custom UIs** - Build React apps with `genai-logic genai-add-app --vibe`
+4. **Add security** - Set up role-based access control with `genai-logic add-auth`
+5. **Test your logic** - Create Behave tests with requirements traceability
+6. **Configure Admin UI** - Customize the auto-generated admin interface
+7. **Add MCP integration** - Enable Model Context Protocol for external AI access
+8. **Create B2B APIs** - Complex integration endpoints with partner systems
+9. **Add events** - Integrate with Kafka, webhooks, or other event systems
+10. **Customize models** - Add tables, attributes, or derived fields
+11. **Discovery systems** - Auto-load logic and APIs from discovery folders
+
+Want to get started? Press **F5** to start the server with debugger support, then open `http://localhost:5656`. (There are also run configurations for running tests and other tasks.) Or just ask me what you'd like to work on.
+
+---
 
 ## 🔑 Key Technical Points
 
@@ -26,54 +69,15 @@ This is a **GenAI-Logic (aka API Logic Server) project** - a complete, working m
 
 3. **Automatic Business Logic**: All APIs (standard and custom) automatically inherit LogicBank rules without additional code.
 
-## ⚠️ IMPORTANT: What's Already Built
-
-**DO NOT recreate these - they're already working:**
-
-1. **Admin Web Application** - Live at `http://localhost:5656`
-2. **REST API Endpoints** - All database tables exposed at `/api/*`
-3. **Database Models** - Complete SQLAlchemy ORM in `database/models.py`
-4. **Authentication System** - JWT-based auth framework
-5. **Business Logic Engine** - Declarative rules system
-
-> **📋 Testing:** For comprehensive testing conventions, patterns, and examples, see `docs/training/testing.md` (555 lines - MUST READ FIRST before creating any tests)
-
-## 🎯 Common Tasks
-
-If the user asks "what do I do now?", these subsections are good suggestions.
-
-List these as choices, do not just do all of them at once - that would be overwhelming.
-
-### 📚 Main Services Available in This Project
-
-This GenAI-Logic project provides 13 main customization services:
+4. **CLI Commands**: Use `genai-logic --help` to see all available commands. When CLI commands exist for a task (e.g., `add-auth`, `genai-add-mcp-client`, `genai-add-app`), ALWAYS use them instead of manual configuration - they handle all setup correctly.
 
-1. **Run Project** - F5 debug or `python api_logic_server_run.py`
-2. **Adding Business Logic** - Declarative rules in `logic/declare_logic.py`
-3. **Discovery Systems** - Auto-load logic and APIs from discovery folders
-4. **Automated Testing** - Behave tests with BLT (Business Logic Traceability) reports
-5. **Adding MCP** - Model Context Protocol client integration
-6. **Configuring Admin UI** - Edit `ui/admin/admin.yaml`
-7. **Create React Apps** - Custom UIs with `genai-logic genai-add-app`
-8. **Security - RBAC** - Role-based access control with `als add-auth`
-9. **Custom API Endpoints** - Add routes in `api/customize_api.py`
-10. **B2B Integration APIs** - Complex endpoints with Row Dict Mappers
-11. **Customize Models** - Add tables, attributes, derived fields
-12. **Adding Events** - Row events for Kafka, webhooks, integrations
-13. **Critical Patterns** - React components, null-safe constraints, test repeatability
-
-Each service is detailed below with examples and best practices.
+> **📋 Testing:** For comprehensive testing conventions, patterns, and examples, see `docs/training/testing.md` (555 lines - I'll read this before we create any tests)
 
 ---
 
-### Set Up Virtual Environment
-If it is not already set, you can often find a `venv` in the GenAI-Logic Manager - a parent or grandparent directory.
-
-### 🚀 To Run This Project
-
-Use F5 (pre-configured run configuration - supports debugger for server logic), or (when focused on client apps):
+## Detailed Service Documentation
 
-```bash
+The sections below provide complete details on each service. I'll reference these as needed when we work together.
 python api_logic_server_run.py
 # Then open: http://localhost:5656
 ```
@@ -417,20 +421,20 @@ Customize using CoPilot chat, with `docs/training`.
 
 Configure:
 ```
-als add-auth --provider-type=sql --db-url=
-als add-auth --provider-type=sql --db_url=postgresql://postgres:p@localhost/authdb
+genai-logic add-auth --provider-type=sql --db-url=
+genai-logic add-auth --provider-type=sql --db_url=postgresql://postgres:p@localhost/authdb
 
-als add-auth --provider-type=keycloak --db-url=localhost
-als add-auth --provider-type=keycloak --db-url=hardened
+genai-logic add-auth --provider-type=keycloak --db-url=localhost
+genai-logic add-auth --provider-type=keycloak --db-url=hardened
 
-als add-auth --provider-type=None # to disable
+genai-logic add-auth --provider-type=None # to disable
 ``` 
 
 Keycloak quick start [(more information here:)](https://apilogicserver.github.io/Docs/Security-Keycloak/)
 ```bash
 cd devops/keycloak
 docker compose up
-als add-auth --provider-type=keycloak --db-url=localhost
+genai-logic add-auth --provider-type=keycloak --db-url=localhost
 ```
 
 For more on KeyCloak: https://apilogicserver.github.io/Docs/Security-Keycloak/
@@ -441,6 +445,64 @@ Declaration:
 Grant(on_entity=Customer, to_role=sales, filter=lambda: Customer.SalesRep == current_user())
 ```
 
+
+#### Testing with Security Enabled
+
+**CRITICAL:** When `SECURITY_ENABLED=True`, test code must obtain and include JWT authentication tokens.
+
+**Pattern for test steps:**
+```python
+from pathlib import Path
+import os
+from dotenv import load_dotenv
+
+# Load config to check SECURITY_ENABLED
+config_path = Path(__file__).parent.parent.parent.parent.parent / 'config' / 'default.env'
+load_dotenv(config_path)
+
+# Cache for auth token (obtained once per test session)
+_auth_token = None
+
+def get_auth_token():
+    """Login and get JWT token if security is enabled"""
+    global _auth_token
+    
+    if _auth_token is not None:
+        return _auth_token
+    
+    # Login with default admin credentials
+    login_url = f'{BASE_URL}/api/auth/login'
+    login_data = {'username': 'admin', 'password': 'p'}
+    
+    response = requests.post(login_url, json=login_data)
+    if response.status_code == 200:
+        _auth_token = response.json().get('access_token')
+        return _auth_token
+    else:
+        raise Exception(f"Login failed: {response.status_code}")
+
+def get_headers():
+    """Get headers including auth token if security is enabled"""
+    security_enabled = os.getenv('SECURITY_ENABLED', 'false').lower() not in ['false', 'no']
+    
+    headers = {'Content-Type': 'application/json'}
+    
+    if security_enabled:
+        token = get_auth_token()
+        if token:
+            headers['Authorization'] = f'Bearer {token}'
+    
+    return headers
+
+# Use in all API requests
+response = requests.post(url=api_url, json=data, headers=get_headers())
+```
+
+**Key points:**
+- Tests DO NOT automatically include auth headers - you must code this pattern
+- Token is cached to avoid repeated logins during test session
+- Pattern works for both `SECURITY_ENABLED=True` and `SECURITY_ENABLED=False`
+- See `test/api_logic_server_behave/features/steps/order_processing_steps.py` for complete example
 ### Adding Custom API Endpoints
 
 For simple endpoints:

api_logic_server_cli/prototypes/base/docs/training/testing.md

@@ -32,6 +32,9 @@ Step 5.  SUGGEST how to run tests (DO NOT run automatically)
   - [ ] @when patterns: carbon neutral > multi-item > single-item
   - [ ] @given patterns: multi-item > single-item
   - [ ] Use `grep -n "@when('.*with" steps/*.py` to verify order
+- [ ] **Clear scenario language?** (Rule #13: Action-oriented wording)
+  - [ ] Use "Order is created" not "Order exists" (shows when rules fire)
+  - [ ] Makes test flow obvious: setup → action → verify
 - [ ] Test data uses timestamps? (Rule #0: Repeatability)
 - [ ] Security config read? (SECURITY_ENABLED value)
 
@@ -167,7 +170,7 @@ def step_impl(context, qty):
     r = requests.patch(url=patch_uri, json=patch_data)
 ```
 
-## The 6 Critical Rules (Read FIRST!)
+## The Critical Rules (Read FIRST!)
 
 ### Rule #0: TEST REPEATABILITY (MOST CRITICAL!) ⚠️
 
@@ -386,18 +389,65 @@ Scenario: Exceed Credit (Constraint FAIL - negative test)
 
 **CRITICAL:** Check `logic/declare_logic.py` for custom Python logic affecting calculations (e.g., discounts, adjustments) before writing constraint test expectations!
 
-### Rule #5: Security Configuration
+### Rule #5: Security Configuration - JWT Authentication
+
+**CRITICAL:** When `SECURITY_ENABLED=True`, tests MUST obtain JWT token and include Authorization header.
+
 ```python
-# Read config/default.env FIRST
-SECURITY_ENABLED = False  # or True
+from pathlib import Path
+import os
+from dotenv import load_dotenv
 
-# Match in test code
-if SECURITY_ENABLED == False:
-    headers = {}  # Empty
-else:
-    headers = test_utils.login()
+# Load config to check SECURITY_ENABLED
+config_path = Path(__file__).parent.parent.parent.parent.parent / 'config' / 'default.env'
+load_dotenv(config_path)
+
+# Cache for auth token (obtained once per test session)
+_auth_token = None
+
+def get_auth_token():
+    """Login and get JWT token if security is enabled"""
+    global _auth_token
+    
+    if _auth_token is not None:
+        return _auth_token
+    
+    # Login with default admin credentials
+    login_url = f'{BASE_URL}/api/auth/login'
+    login_data = {'username': 'admin', 'password': 'p'}
+    
+    response = requests.post(login_url, json=login_data)
+    if response.status_code == 200:
+        _auth_token = response.json().get('access_token')
+        return _auth_token
+    else:
+        raise Exception(f"Login failed: {response.status_code}")
+
+def get_headers():
+    """Get headers including auth token if security is enabled"""
+    security_enabled = os.getenv('SECURITY_ENABLED', 'false').lower() not in ['false', 'no']
+    
+    headers = {'Content-Type': 'application/json'}
+    
+    if security_enabled:
+        token = get_auth_token()
+        if token:
+            headers['Authorization'] = f'Bearer {token}'
+    
+    return headers
+
+# Use in ALL API requests
+response = requests.post(url=api_url, json=data, headers=get_headers())
+response = requests.get(url=api_url, headers=get_headers())
+response = requests.patch(url=api_url, json=data, headers=get_headers())
 ```
 
+**Key Points:**
+- Tests DO NOT automatically include auth - you must code the pattern above
+- Token is cached globally to avoid repeated login calls
+- Works for both `SECURITY_ENABLED=True` and `SECURITY_ENABLED=False`
+- See complete example: `test/api_logic_server_behave/features/steps/order_processing_steps.py`
+
 ### Rule #6: Logic Logging
 ```python
 @when('Good Order Placed')
@@ -535,6 +585,40 @@ def step_impl(context):
         return  # Skip gracefully
 ```
 
+### Rule #13: Use Clear, Action-Oriented Scenario Language ⚠️ NEW
+```gherkin
+# ❌ AMBIGUOUS - "exists" is passive, doesn't show when balance changes
+Scenario: Ship Order Excludes from Balance
+  Given Customer "Charlie" with balance 0 and credit limit 2000
+  And Order exists for "Charlie" with 2 Widget
+  When Order is shipped
+  Then Customer balance should be 0
+
+# Question: How can Charlie have balance 0 AND an order for widgets?
+# Answer: The order EXISTS at test start, but balance calculation is unclear
+
+# ✅ CLEAR - "is created" shows action that triggers rule
+Scenario: Ship Order Excludes from Balance
+  Given Customer "Charlie" with balance 0 and credit limit 2000
+  And Order is created for "Charlie" with 2 Widget  # Action! Balance becomes 180
+  When Order is shipped                              # Action! Balance drops to 0
+  Then Customer balance should be 0                  # Verification
+
+# Now it's obvious:
+# 1. Customer starts with balance 0
+# 2. Creating unshipped order → rule fires → balance becomes 180
+# 3. Shipping order → WHERE clause excludes it → balance drops to 0
+
+# More examples:
+# ❌ "And Shipped order exists for..."
+# ✅ "And Shipped order is created for..."
+
+# Why this matters:
+# - Shows WHEN rules fire (on creation, not just existence)
+# - Makes test flow obvious (setup → action → verify)
+# - Clarifies that declarative rules execute automatically on changes
+```
+
 ## Complete Phase 2 Example
 
 ### .feature File
@@ -631,6 +715,8 @@ def step_impl(context, expected):
 | **"balance: expected 570, got 0.0"** | **Step ordering issue (Rule #0.5)! Multi-item pattern after single-item** |
 | **"context has no attribute 'item_id'"** | **Step ordering issue! Specific pattern defined after general pattern** |
 | "Order created but no items" | Check if wrong step matched (print debug in step) |
+| **"expected 810, got 900"** (carbon neutral) | **Rule #10: Verify actual database values! Check product flags with SQL first** |
+| **"How can balance be 0 with an order?"** | **Rule #13: Use "is created" not "exists" - shows when rules fire** |
 
 ### Debugging Step Ordering Issues
 

api_logic_server_cli/prototypes/base/test/api_logic_server_behave/behave_logic_report.py

@@ -129,19 +129,32 @@ def show_logic(scenario: str, logic_logs_dir: str):
             best_section = max(rules_sections, key=lambda x: x['rule_count'])
             last_rules_start = best_section['start']
             last_rules_end = best_section['end']
+            # Find where the "These Rules Fired" line is (one line before rules start)
+            rules_fired_line = last_rules_start - 1
+            # Now search backwards to find the beginning of this logic section
+            logic_start_line = rules_fired_line - 1
+            while logic_start_line > 0:
+                line = logic_lines[logic_start_line].strip()
+                # Look for the start marker (usually after a blank line following "COMPLETE")
+                if 'Logic Phase:' in logic_lines[logic_start_line] and 'ROW LOGIC' in logic_lines[logic_start_line]:
+                    # Found the start of the logic section
+                    # Go back one more to include the header line (scenario name)
+                    if logic_start_line > 0 and logic_lines[logic_start_line-1].strip():
+                        logic_start_line -= 1
+                    break
+                logic_start_line -= 1
         else:
             last_rules_start = -1
             last_rules_end = -1
+            logic_start_line = 0
                     
-        # Now process the file, collecting logic log and extracting the last rules section
+        # Now process the file, collecting logic log and extracting the rules section
         for i, each_logic_line in enumerate(logic_lines):
             each_logic_line = remove_trailer(each_logic_line)
             
-            if is_logic_log:
-                if "These Rules Fired" in each_logic_line:
-                    is_logic_log = False
-                else:
-                    logic_log.append(each_logic_line)
+            # Collect logic log from the best section
+            if rules_sections and logic_start_line <= i < rules_fired_line:
+                logic_log.append(each_logic_line)
             
             # Extract rules from the last "These Rules Fired" section
             if last_rules_start <= i < last_rules_end: