@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/templates/business-service/gitignore

@@ -0,0 +1,42 @@
+# Dependencies
+node_modules/
+
+# Runtime data
+config/runtime/
+config/env-active/
+
+# Validation proof written by `npm run test:cookbooks` (the validator's own CLI)
+# and by the wrapper on every boot — generated, never committed (same line
+# api_biz/hello-service carries).
+conn-runtime/
+
+# Deployability signal written by the manifest step of the boot validation and
+# by `npx oa-validate` (`ci/deployability.json`, the shape of
+# `ci/integration-signal.json`) - generated on every start, never committed.
+ci/
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+
+# Coverage
+coverage/
+
+# Environment (legacy)
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+.oa_drive_deps_hash

package/templates/business-service/index.js

@@ -0,0 +1,10 @@
+/**
+ * __SERVICE_NAME__ - Main Entry Point
+ * Uses unified bootstrap from @onlineapps/service-wrapper
+ */
+const { bootstrap } = require('@onlineapps/service-wrapper');
+
+bootstrap(__dirname).catch(error => {
+  console.error('Failed to start service:', error);
+  process.exit(1);
+});

package/templates/business-service/init.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+set -e
+
+oa_npm_install() {
+  npm install --no-audit --no-fund
+}
+
+# --- oa-deps-guard v1 (identical in every OA Drive init.sh) ---
+# The dev stack's only skip condition: the md5 of package.json + package-lock.json
+# against the marker the last SUCCESSFUL install wrote. A package-directory probe
+# cannot see a version bump and an mtime probe cannot see a checkout that rewinds
+# package.json, so neither is used here or anywhere else in the file. Enforced byte
+# for byte, within this repo, by tests/scripts/infra-init-scripts.bats — across the
+# eight infra/*/init.sh, this template and the generator's output. A copy pasted
+# into an api_biz/* repo is kept in sync by review only; the gate cannot reach
+# another checkout. A service's own install steps belong in oa_npm_install() above,
+# everything else it needs goes below.
+MARKER_FILE=".oa_drive_deps_hash"
+
+HASH_INPUT=""
+if [ -f "package.json" ]; then
+  HASH_INPUT="${HASH_INPUT}$(md5sum package.json | awk '{print $1}')"
+fi
+if [ -f "package-lock.json" ]; then
+  HASH_INPUT="${HASH_INPUT}$(md5sum package-lock.json | awk '{print $1}')"
+fi
+CURRENT_HASH=$(echo "$HASH_INPUT" | md5sum | awk '{print $1}')
+
+PREVIOUS_HASH=""
+if [ -f "$MARKER_FILE" ]; then
+  PREVIOUS_HASH=$(cat "$MARKER_FILE" 2>/dev/null || true)
+fi
+
+NEEDS_INSTALL=0
+if [ ! -d "node_modules" ] || [ -z "$(ls -A node_modules 2>/dev/null)" ]; then
+  NEEDS_INSTALL=1
+fi
+
+if [ "$CURRENT_HASH" != "$PREVIOUS_HASH" ] || [ "$NEEDS_INSTALL" = "1" ]; then
+  echo "[init.sh] Installing dependencies (hash changed or node_modules missing)..."
+  if oa_npm_install; then
+    echo "$CURRENT_HASH" > "$MARKER_FILE"
+    echo "[init.sh] Dependencies installed, marker $MARKER_FILE updated."
+  else
+    echo "[init.sh] Dependency install failed - marker $MARKER_FILE left untouched, so the next start retries instead of trusting a half-installed tree. Fix: read the npm error above, then run 'npm install' in this service directory."
+    exit 1
+  fi
+else
+  echo "[init.sh] Dependencies unchanged. Skipping npm install."
+fi
+# --- end oa-deps-guard v1 ---
+
+# Run the passed command (e.g. npm run dev or npm run prod).
+exec "$@"

package/templates/business-service/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.js'],
+  testTimeout: 30000,
+  maxWorkers: 1
+};

package/templates/business-service/package.json.template

@@ -0,0 +1,31 @@
+{
+  "name": "__REGISTRY_NAME__",
+  "version": "1.0.0",
+  "private": true,
+  "main": "index.js",
+  "engines": {
+    "node": ">=24.0.0 <25"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "dev": "nodemon index.js",
+    "test": "jest --config jest.config.js tests/unit --runInBand",
+    "test:ci": "jest",
+    "test:unit": "jest tests/unit",
+    "test:all": "npm run test:unit",
+    "test:container": "docker compose run --rm __CONTAINER_NAME___tests npm run test:unit",
+    "test:all:container": "docker compose run --rm __CONTAINER_NAME___tests npm run test:all",
+    "test:coverage": "jest --coverage",
+    "test:cookbooks": "node node_modules/@onlineapps/conn-orch-validator/src/cli/biz-ci-gate.js run-prevalidation",
+    "test:cookbooks:container": "docker compose run --rm __CONTAINER_NAME___tests npm run test:cookbooks"
+  },
+  "dependencies": {
+    "@onlineapps/conn-orch-validator": "__SSOT_PIN__",
+    "@onlineapps/service-wrapper": "__SSOT_PIN__",
+    "@onlineapps/service-common": "__SSOT_PIN__"
+  },
+  "devDependencies": {
+    "jest": "29.7.0",
+    "nodemon": "3.1.7"
+  }
+}

package/templates/business-service/scripts/verify-deploy-uniform.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env sh
+# Owns: refusing this service's production deploy unless the COMPLETE biz-service uniform run over the checkout being deployed comes back green
+# Usage: verify-deploy-uniform.sh <serviceRoot> <apiRepositoryUrl> <apiRef>
+# Shell: sh
+# Exit: 0 deployable and complete | 1 a blocking finding, or a run that did not look everywhere | 2 the check itself could not run
+# Status: current
+#
+# @see api/docs/governance/confirmations/biz-service-manifest.md
+# @see api/docs/governance/confirmations/server-topology.md
+#
+# WHY IT EXISTS. Confirmation `biz-service-manifest` 006 point 3 and 008: a biz
+# service is deployed by its own repository's CI (`server-topology` 004), so the
+# last place that can refuse an unfit deploy is this repository's own
+# `deploy-production` job, before the SSH step. Deploy is CONFIRMATION, never
+# discovery — the same run has already happened on the developer's machine at
+# push time (006 point 1) — but a confirmation that is skipped when it is
+# inconvenient is not one, so there is no flag, no variable and no branch that
+# turns this off (`automation-gates.md` §1 requirement 5).
+#
+# ONE job (§1.2): measure, and refuse. It fixes nothing, writes nothing into the
+# repository beyond the signal the engine itself records, and judges nothing on
+# its own: every row lives in the manifest inside @onlineapps/conn-orch-validator
+# and the engine's own exit code and signal are the verdict, so the uniform has
+# one implementation (`change-discipline.md` § One rail per concern).
+#
+# WHY A FILE RATHER THAN A HEREDOC IN .gitlab-ci.yml. A heredoc can only ever be
+# run by GitLab: it cannot be executed, tested or read back locally, so the one
+# place the gate would be proven is production. This file is called by the job
+# with three arguments and by `api/tests/scripts/biz-deploy-uniform-gate.bats`
+# with three others, and both run the same bytes.
+#
+# WHY THREE ARGUMENTS AND NOTHING FROM THE ENVIRONMENT. The script knows what to
+# measure, never where the pieces come from (`architecture-principles.md` §1):
+# the job passes the checkout GitLab made, the api repository URL carrying its
+# job token, and the api ref that production follows. Nothing here reads
+# `process.env`, so the same invocation is reproducible outside CI.
+#
+# THE LAYOUT IT NEEDS, AND WHY THE JOB HAS TO ASK FOR IT. The engine answers the
+# rows that read the platform SSOT only for a service that lies at
+# <root>/api_biz/<service> beside <root>/api — measured 2026-09-11 over a
+# converter export: in that layout the run is complete in about a second, and
+# with the same two directories as unrelated siblings seven blocking rows come
+# back NOT RUN (U-ORPHAN, U-IDENTITY, D-PORT, D-NPM, D-SCRIPT, D-RETIRED,
+# D-HEADER) and the signal reads complete: false. A symlink is forbidden
+# (`api/.claude/rules/architecture-principles.md` § No Symlinks) and a second
+# copy of this repository would leave two trees where the reader has to ask which
+# one was measured, so the JOB asks GitLab to check the project out in the right
+# place (GIT_CLONE_PATH) and this script verifies that it did.
+
+set -eu
+
+CONTEXT="deploy-uniform"
+
+# Every failure names what was checked, what was expected and the command that
+# fixes it (`architecture-principles.md` §5, `automation-gates.md` §1.4).
+die() { # <message> <exit-code>
+  echo "[$CONTEXT] $1" >&2
+  exit "$2"
+}
+
+# --- arguments --------------------------------------------------------------
+
+if [ "$#" -ne 3 ]; then
+  die "Wrong number of arguments - got $#, expected 3. Usage: verify-deploy-uniform.sh <serviceRoot> <apiRepositoryUrl> <apiRef>" 2
+fi
+
+SERVICE_ROOT="$1"
+API_URL="$2"
+API_REF="$3"
+
+[ -n "$API_URL" ] || die "The api repository URL is empty - the uniform reads the platform SSOT from that checkout, and this script does not guess where it lives. Expected: the URL the job builds from CI_JOB_TOKEN. Fix: pass it as the second argument." 2
+[ -n "$API_REF" ] || die "The api ref is empty - which state of the platform this deploy is measured against is a decision, not a default. Expected: the branch production follows. Fix: pass it as the third argument." 2
+[ -d "$SERVICE_ROOT" ] || die "Service root not found - '$SERVICE_ROOT' is not an existing directory. Expected: the checkout being deployed. Fix: pass \$CI_PROJECT_DIR." 2
+
+SERVICE_ROOT=$(cd "$SERVICE_ROOT" && pwd)
+CONTAINER_DIR=$(dirname "$SERVICE_ROOT")
+WORKSPACE_ROOT=$(dirname "$CONTAINER_DIR")
+API_CHECKOUT="$WORKSPACE_ROOT/api"
+
+if [ "$(basename "$CONTAINER_DIR")" != "api_biz" ]; then
+  die "The checkout is not in the layout the uniform needs - $SERVICE_ROOT lies in '$(basename "$CONTAINER_DIR")', and the engine answers the rows that read the platform SSOT only for a service under <root>/api_biz/ beside <root>/api. Expected: the job checks this project out there. Fix: in .gitlab-ci.yml set the job variable GIT_CLONE_PATH: \$CI_BUILDS_DIR/oa-uniform/api_biz/<service>, and confirm the runner allows a custom build directory ([runners.custom_build_dir] enabled)." 2
+fi
+
+command -v git >/dev/null 2>&1 || die "Missing tool - 'git' does not run, and the api checkout this run reads cannot be fetched without it. Fix: install git in the job image (apk add --no-cache git)." 2
+command -v node >/dev/null 2>&1 || die "Missing tool - 'node' does not run, and the run's signal (ci/deployability.json) cannot be read without it. Fix: run this job on the platform node image." 2
+
+# --- the api checkout -------------------------------------------------------
+#
+# Read-only and shallow: the uniform reads files, never history. A runner reuses
+# its builds directory between pipelines, so a checkout left by an earlier run
+# would silently measure this deploy against a stale SSOT — it is removed and
+# fetched again, and only when it is recognisably this script's own artefact.
+if [ -e "$API_CHECKOUT" ]; then
+  if [ -d "$API_CHECKOUT/.git" ] && [ -f "$API_CHECKOUT/config/services.json" ]; then
+    rm -rf "$API_CHECKOUT"
+  else
+    die "Cannot place the api checkout - $API_CHECKOUT already exists and is not an api clone this script made (no .git and config/services.json). Expected: that path free, or an earlier clone of the api repository. Fix: remove it, or point the job's GIT_CLONE_PATH at a build directory this pipeline owns." 2
+  fi
+fi
+
+# The token never reaches the log: messages print the URL with its userinfo cut out.
+SAFE_URL=$(printf '%s' "$API_URL" | sed -e 's#//[^@/]*@#//#')
+
+if ! git clone --depth 1 --single-branch --branch "$API_REF" "$API_URL" "$API_CHECKOUT"; then
+  die "The api checkout could not be cloned - git clone --branch $API_REF $SAFE_URL failed, so api/config/services.json cannot be read and the uniform would answer a fraction of its rows. A partial answer is not a deploy permit, so this refuses rather than continues. Expected: read access for this pipeline's job token. Fix: in GitLab open the api project, Settings > CI/CD > Job token permissions, and add this project to the allowlist (owner's step, confirmation biz-service-manifest 008 point 2); check also that the ref '$API_REF' exists there." 2
+fi
+
+# --- the engine -------------------------------------------------------------
+#
+# The pin decides which uniform this service is measured against, so the engine
+# is the one this repository installed — never a floating npx download, which
+# would measure a version this service never proved.
+ENGINE="$SERVICE_ROOT/node_modules/.bin/oa-validate"
+if [ ! -x "$ENGINE" ]; then
+  die "Missing engine - $ENGINE is not there, so the uniform cannot be measured, and this step does not wave through a check it could not run. Expected: @onlineapps/conn-orch-validator installed from the pin in package.json. Fix: run 'npm ci' in this job before this step." 2
+fi
+
+echo "[$CONTEXT] Checking the checkout being deployed against the biz-service uniform (confirmation biz-service-manifest 008):"
+echo "  service:   $SERVICE_ROOT"
+echo "  workspace: $WORKSPACE_ROOT"
+echo "  api:       $SAFE_URL ($API_REF)"
+
+# The table is printed whatever the verdict: a green run is evidence too, and a
+# red one is only actionable with its rows in the job log.
+set +e
+"$ENGINE" "$SERVICE_ROOT" --workspace "$WORKSPACE_ROOT"
+ENGINE_RC=$?
+set -e
+
+if [ "$ENGINE_RC" -ne 0 ]; then
+  echo "" >&2
+  die "Refused - this service does not wear the uniform (engine exit $ENGINE_RC); the table above lists every row that found something, with the fix for each. Expected: no finding of a severity that blocks. Fix: follow the fix column in this repository, push, and deploy the commit that is green." 1
+fi
+
+# --- completeness -----------------------------------------------------------
+#
+# `deployable` says nothing blocked among the rows that RAN; `complete` says no
+# row that CAN block was skipped. Reading only the first would honour a skip
+# nobody flagged (`automation-gates.md` §1.5). The signal file is transport
+# inside this job and nothing else: it carries no sha, so a file found in a
+# working tree proves nothing about which tree it measured (008 point 1).
+SIGNAL="$SERVICE_ROOT/ci/deployability.json"
+if [ ! -f "$SIGNAL" ]; then
+  die "Missing signal - the run finished but wrote no $SIGNAL, so whether it looked everywhere is unknown, and an unanswered question is not a pass. Fix: run '$ENGINE $SERVICE_ROOT --workspace $WORKSPACE_ROOT' by hand and read the error it prints." 2
+fi
+
+set +e
+VERDICT=$(node -e '
+  const fs = require("fs");
+  let signal;
+  try {
+    signal = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  } catch (error) {
+    process.stderr.write(error.message + "\n");
+    process.exit(2);
+  }
+  if (signal.complete !== true) {
+    for (const row of signal.notRun || []) {
+      process.stdout.write(`  ${row.id}  ${row.reason}\n`);
+    }
+    process.exit(3);
+  }
+  if (signal.deployable !== true) process.exit(4);
+  process.exit(0);
+' "$SIGNAL")
+SIGNAL_RC=$?
+set -e
+
+case "$SIGNAL_RC" in
+  0) ;;
+  2) die "Cannot read the signal - $SIGNAL is not readable JSON, so whether the run looked everywhere is unknown. Fix: delete it and run '$ENGINE $SERVICE_ROOT --workspace $WORKSPACE_ROOT' again." 2 ;;
+  3)
+    echo "" >&2
+    echo "$VERDICT" >&2
+    die "Refused - the run was incomplete: the rows above could not look, and a run that answered part of the manifest proves nothing about the rest. Expected: complete=true in $SIGNAL. Fix: give the run the layout it names - the api checkout beside this one under <root>/api_biz/<service>." 1 ;;
+  4) die "Refused - the engine reported no blocking finding and the signal says this service is not deployable; the two disagree, and the refusing answer is the one this step takes. Fix: read $SIGNAL and the table above." 1 ;;
+  *) die "Cannot read the signal - reading $SIGNAL ended with exit $SIGNAL_RC, which this step has no meaning for. Fix: run '$ENGINE $SERVICE_ROOT --workspace $WORKSPACE_ROOT' by hand and read what it prints." 2 ;;
+esac
+
+echo "[$CONTEXT] DEPLOYABLE - the uniform run over this checkout is complete and carries no blocking finding."

package/templates/business-service/src/handlers/v3/echo.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * Echo handler (v3 invocation model) — the example operation this template
+ * ships so a new service starts from a shape that already works.
+ *
+ * A biz service binds no port (ADR 0005): an operation is a plain exported
+ * function, reached over MQ in production and called directly by the Tier-1
+ * runner. There is no route, no request and no response object here.
+ *
+ * The behaviour is deliberately total and deterministic — the same input
+ * always yields the same output — so the cookbook beside it can assert a
+ * CONCRETE VALUE rather than that something truthy came back
+ * (.claude/rules/architecture-principles.md §10a).
+ *
+ * Input shape is guaranteed by SchemaValidator against the `input` schema in
+ * config/service/operations.json, so this function does not re-check it.
+ *
+ * @see api/docs/biz/10-invocation/handler-dispatch.md
+ * @see api/docs/biz/30-operations/schema-v3.md § handler
+ *
+ * @param {{text: string}} input - validated against the operation's input schema
+ * @param {Object} ctx - built by ContextBuilder in production, by the Tier-1 runner in validation
+ * @returns {Promise<{text: string, length: number}>}
+ */
+async function echo(input, ctx) {
+  const { text } = input;
+  const { logger, operation_name, correlation_id } = ctx;
+
+  logger.info('returning submitted text unchanged', {
+    length: text.length,
+    operation_name,
+    correlation_id
+  });
+
+  return { text, length: text.length };
+}
+
+module.exports = { echo };

package/templates/business-service/tests/cookbooks/echo.json

@@ -0,0 +1,36 @@
+{
+  "version": "2.1.0",
+  "name": "echo",
+  "description": "Tier-1 cookbook for the example echo operation: the submitted text comes back unchanged, with its length.",
+  "test": {
+    "mode": "offline",
+    "timeout": 5000
+  },
+  "steps": [
+    {
+      "step_id": "echo_text",
+      "type": "task",
+      "service": "__REPO_NAME__",
+      "operation": "echo",
+      "input": {
+        "text": "cookbook"
+      },
+      "expect": {
+        "status": "success",
+        "output": {
+          "text": {
+            "type": "string",
+            "equals": "cookbook"
+          },
+          "length": {
+            "type": "number",
+            "equals": 8
+          }
+        }
+      }
+    }
+  ],
+  "delivery": {
+    "handler": "none"
+  }
+}

package/templates/business-service/tests/unit/handler.test.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// Unit test for the example v3 handler this template ships. A biz service has
+// no app to mount and no port to bind (ADR 0005): a handler is a plain
+// function, so its test requires the module and calls it directly — no
+// supertest, no HTTP, no DB.
+//
+// Replace this file when you replace src/handlers/v3/echo.js with your own
+// operation. Keep the shape: assert CONCRETE VALUES, cover the failure path,
+// and keep a control case that must not move
+// (.claude/rules/architecture-principles.md §10a).
+
+const { echo } = require('../../src/handlers/v3/echo');
+
+/** The ctx slots the Tier-1 runner and ContextBuilder both fill. */
+function makeCtx(overrides = {}) {
+  const lines = [];
+  return {
+    ctx: {
+      logger: { info: (msg, meta) => lines.push({ msg, meta }), warn: () => {}, error: () => {} },
+      operation_name: 'echo',
+      correlation_id: 'test-correlation-id',
+      ...overrides
+    },
+    lines
+  };
+}
+
+describe('echo handler @unit', () => {
+  it('returns the submitted text unchanged, with its length', async () => {
+    const { ctx } = makeCtx();
+
+    const result = await echo({ text: 'cookbook' }, ctx);
+
+    expect(result).toEqual({ text: 'cookbook', length: 8 });
+  });
+
+  it('counts an empty string as length 0 rather than reporting nothing', async () => {
+    const { ctx } = makeCtx();
+
+    const result = await echo({ text: '' }, ctx);
+
+    expect(result).toEqual({ text: '', length: 0 });
+  });
+
+  it('logs the length it computed, on the injected logger', async () => {
+    const { ctx, lines } = makeCtx();
+
+    await echo({ text: 'abc' }, ctx);
+
+    expect(lines).toHaveLength(1);
+    expect(lines[0].meta).toEqual({
+      length: 3,
+      operation_name: 'echo',
+      correlation_id: 'test-correlation-id'
+    });
+  });
+
+  // Failure path: ctx is injected, never defaulted. A handler that fell back to
+  // console here would log outside the service's own stream and the caller
+  // would never learn the ctx was wrong (architecture-principles.md §3).
+  it('fails loudly when ctx carries no logger, instead of falling back', async () => {
+    await expect(echo({ text: 'abc' }, {})).rejects.toThrow(TypeError);
+  });
+
+  // Control: the handler declares no state, so a second call with the same
+  // input returns the same value. This must not change when the operation
+  // beside it does.
+  it('CONTROL: is deterministic — the same input twice gives the same output', async () => {
+    const { ctx } = makeCtx();
+
+    const first = await echo({ text: 'same' }, ctx);
+    const second = await echo({ text: 'same' }, ctx);
+
+    expect(second).toEqual(first);
+    expect(first).toEqual({ text: 'same', length: 4 });
+  });
+});