@onlineapps/conn-orch-validator 3.3.1 → 3.3.2

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [3.3.2] — 2026-08-17
+
+**ServiceStructureValidator refactor for ADR 0005 / Fáze F6 reality.**
+
+3.3.1 still required `src/app.js`, `service.port`, and `businessErrorHandler in src/app.js` — all dead after F6 removed Express. Any biz service whose validation-proof got invalidated post-F6 would hit `MISSING_APP` at Tier-1 step 1 and stall in restart loop. Surfaced when biz-meta's proof was manually invalidated in the Fáze F7 followup.
+
+### BREAKING
+
+- **v1.0 Base Service Standard**: `src/app.js` no longer required. `src/handlers/` is now the required source dir (flat or `handlers/v3/` subdir — both are canonical variants). `service.port` no longer required in `config.json`.
+- **v1.2 Business Error Handling**: `businessErrorHandler in src/app.js` check REMOVED (there is no src/app.js). Replaced with: at least one handler under `src/handlers/` imports and throws a `BusinessError` family class (`ValidationError`, `NotFoundError`, `ConflictError`, `ForbiddenError`) from `@onlineapps/service-common`. Errors flow through the wrapper's `ErrorMapper` post-A2.2, not through Express middleware.
+- **`validateSourceStructure()`**: `MISSING_APP` error replaced with `MISSING_HANDLERS`. Presence of `src/app.js` now emits a **warning** (`LEGACY_APP_JS`) — dead code that F6 removes.
+
+### Added
+
+- **v1.3 Zero-HTTP Shape (ADR 0005)** — new standard level asserting F6 cleanup landed:
+  - `src/app.js` absent
+  - `src/routes/` absent
+  - `src/middlewares/` absent
+  - `express` NOT in `package.json` dependencies
+
+### Rationale
+
+Every biz service on the platform is post-F6 (verified in Fáze F acceptance ledger). Continuing to require Express artefacts would false-positive-fail every valid v3-canonical service.
+
+### Tests
+
+Unit suite 158/158 GREEN before publish. Note: standard-level tests
+(`StandardLevels.test.js`) were rewritten in the same commit to match
+the post-F6 rules — 6 pre-existing test cases replaced with 6 matching
+the new spec.
+
 ## [3.3.1] — 2026-08-17
 
 **Tier-1 step 5 refactor: retire HTTP `/health` probe per ADR 0005.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-validator",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "Validation orchestrator for OA Drive microservices - coordinates validation across all layers (base, infra, orch, business)",
   "main": "src/index.js",
   "bin": {

package/src/validators/ServiceStructureValidator.js

@@ -50,7 +50,9 @@ const STANDARD_LEVELS = [
       results.push({ passed: hasConfigDir(root), id: 'dir_conn_config', message: 'config/service/ or conn-config/ directory' });
       results.push({ passed: has('src'), id: 'dir_src', message: 'src/ directory' });
       results.push({ passed: has('tests'), id: 'dir_tests', message: 'tests/ directory' });
-      results.push({ passed: has('src/app.js'), id: 'file_app', message: 'src/app.js' });
+      // ADR 0005: src/handlers/ replaces src/app.js. Flat handlers/ or
+      // handlers/v3/ subdir are both valid canonical shapes.
+      results.push({ passed: has('src/handlers'), id: 'dir_handlers', message: 'src/handlers/ (v3 handler modules)' });
       results.push({ passed: has('index.js'), id: 'file_index', message: 'index.js entry point' });
 
       const configRaw = readConfigFile(root, 'config.json');
@@ -58,10 +60,11 @@ const STANDARD_LEVELS = [
       if (configRaw) {
         try {
           const cfg = JSON.parse(configRaw);
-          configValid = !!(cfg.service?.name && cfg.service?.port);
+          // ADR 0005: service.port not required post zero-HTTP. Just name.
+          configValid = !!cfg.service?.name;
         } catch { /* invalid JSON */ }
       }
-      results.push({ passed: configValid, id: 'config_valid', message: 'Valid config.json with service.name + service.port' });
+      results.push({ passed: configValid, id: 'config_valid', message: 'Valid config.json with service.name' });
 
       const opsRaw = readConfigFile(root, 'operations.json');
       let opsValid = false;
@@ -120,12 +123,63 @@ const STANDARD_LEVELS = [
         } catch { /* invalid JSON */ }
       }
 
-      const appContent = read('src/app.js') || '';
-      const hasErrorMiddleware = appContent.includes('businessErrorHandler');
+      // ADR 0005 / F6: businessErrorHandler was Express middleware in
+      // src/app.js. Post-F6 there is no src/app.js. Error handling now
+      // happens via BusinessError thrown from handlers → wrapper's
+      // ErrorMapper. Check: at least one handler imports a
+      // BusinessError-family class from @onlineapps/service-common.
+      const handlersDir = path.join(root, 'src', 'handlers');
+      let hasBusinessErrorUsage = false;
+      if (fs.existsSync(handlersDir)) {
+        const walk = (dir) => {
+          for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const p = path.join(dir, entry.name);
+            if (entry.isDirectory()) walk(p);
+            else if (entry.isFile() && entry.name.endsWith('.js')) {
+              const content = read(path.relative(root, p));
+              if (content && /@onlineapps\/service-common/.test(content) &&
+                  /BusinessError|ValidationError|NotFoundError|ConflictError|ForbiddenError/.test(content)) {
+                hasBusinessErrorUsage = true;
+              }
+            }
+          }
+        };
+        try { walk(handlersDir); } catch { /* ignore */ }
+      }
 
       return [
         { passed: hasServiceCommon, id: 'dep_service_common', message: '@onlineapps/service-common dependency' },
-        { passed: hasErrorMiddleware, id: 'error_middleware', message: 'businessErrorHandler middleware in src/app.js' }
+        { passed: hasBusinessErrorUsage, id: 'business_error_usage', message: 'At least one handler throws a BusinessError family from @onlineapps/service-common' }
+      ];
+    }
+  },
+  {
+    level: 'v1.3',
+    name: 'Zero-HTTP Shape (ADR 0005)',
+    since: '2026-08-17',
+    checks: (root) => {
+      const has = (p) => fs.existsSync(path.join(root, p));
+      const read = (p) => { try { return fs.readFileSync(path.join(root, p), 'utf-8'); } catch { return null; } };
+
+      // v1.3 asserts that F6/A2 cleanup landed: no dead Express surface.
+      const noAppJs = !has('src/app.js');
+      const noRoutesDir = !has('src/routes');
+      const noMiddlewaresDir = !has('src/middlewares');
+
+      const pkgRaw = read('package.json');
+      let noExpressDep = true;
+      if (pkgRaw) {
+        try {
+          const pkg = JSON.parse(pkgRaw);
+          noExpressDep = !pkg.dependencies?.express;
+        } catch { /* invalid JSON — separate check catches it */ }
+      }
+
+      return [
+        { passed: noAppJs, id: 'no_app_js', message: 'src/app.js absent (retired Express dispatch surface)' },
+        { passed: noRoutesDir, id: 'no_routes_dir', message: 'src/routes/ absent (dead HTTP route mounts)' },
+        { passed: noMiddlewaresDir, id: 'no_middlewares_dir', message: 'src/middlewares/ absent (dead Express middleware)' },
+        { passed: noExpressDep, id: 'no_express_dep', message: 'express not in package.json dependencies' }
       ];
     }
   }
@@ -594,39 +648,45 @@ class ServiceStructureValidator {
   }
 
   /**
-   * Validate source code structure
+   * Validate source code structure.
+   *
+   * ADR 0005 (2026-08-17): biz containers have zero HTTP surface —
+   * no Express, no `src/app.js`, no per-op HTTP routes. The v3
+   * handler-registry model instead requires `src/handlers/` (flat
+   * or `handlers/v3/` subdir — both variants of the canonical
+   * shape) with `handler` refs from `operations.json` resolvable
+   * to real exports.
    */
   validateSourceStructure() {
-    const appPath = path.join(this.serviceRoot, 'src/app.js');
-    if (!fs.existsSync(appPath)) {
+    // Post-ADR-0005 hard requirement: at least one handler module
+    // (flat or under v3/) must exist. HandlerRegistry.validate() at
+    // bootstrap time enforces per-op resolution; here we just ensure
+    // the directory itself is present so the service has something
+    // to dispatch to.
+    const handlersFlat = path.join(this.serviceRoot, 'src/handlers');
+    if (!fs.existsSync(handlersFlat)) {
       this.errors.push({
-        type: 'MISSING_APP',
-        path: 'src/app.js',
-        message: 'Express application missing: src/app.js',
-        fix: 'Create src/app.js with Express app. See: /docs/biz/60-templates/service-template.md'
+        type: 'MISSING_HANDLERS',
+        path: 'src/handlers',
+        message: 'Handlers directory missing: src/handlers/',
+        fix: 'Create src/handlers/ with at least one v3 handler module. See: /docs/biz/60-templates/service-template.md'
       });
     } else {
-      this.info.push('✓ Found src/app.js');
+      this.info.push('✓ Found src/handlers/');
+    }
 
-      try {
-        const appContent = fs.readFileSync(appPath, 'utf-8');
-        if (appContent.includes('businessErrorHandler')) {
-          this.info.push('✓ businessErrorHandler middleware registered');
-        } else {
-          this.warnings.push({
-            type: 'MISSING_ERROR_MIDDLEWARE',
-            path: 'src/app.js',
-            message: 'businessErrorHandler middleware not found in src/app.js',
-            fix: 'Register businessErrorHandler from @onlineapps/service-common as Express error middleware. See: /docs/standards/ERROR_HANDLING.md'
-          });
-        }
-      } catch (readError) {
-        this.warnings.push({
-          type: 'UNREADABLE_APP',
-          path: 'src/app.js',
-          message: `Could not read src/app.js: ${readError.message}`
-        });
-      }
+    // src/app.js is ANTI-PATTERN post-ADR 0005 (dead Express surface).
+    // Warn if present so authors of new services notice they should
+    // remove it; existing services scheduled to be cleaned up via the
+    // Fáze F6 pass.
+    const appPath = path.join(this.serviceRoot, 'src/app.js');
+    if (fs.existsSync(appPath)) {
+      this.warnings.push({
+        type: 'LEGACY_APP_JS',
+        path: 'src/app.js',
+        message: 'src/app.js is dead code post-ADR 0005 (bootstrap no longer reads it)',
+        fix: 'Delete src/app.js; move any residual middleware into the wrapper adapter. See: /docs/biz/80-decisions/0005-no-http-in-biz-containers.md'
+      });
     }
 
     const indexPath = path.join(this.serviceRoot, 'index.js');