@onlineapps/cookbook-template-helpers 1.0.14 → 2.0.0

package/README.md

@@ -49,6 +49,15 @@ Převede file/inline descriptor na string (přes ContentResolver). File stáhne
 async function file2string(descriptor, context)
 ```
 
+### Helper context — logger
+
+Oba descriptor helpery si staví `ContentResolver`, pokud jim v kontextu nepředáš
+hotový `context.contentResolver`. V tom případě je `context.logger` **povinný** a
+musí mít všechny čtyři metody: `info()`, `warn()`, `error()`, `debug()` — přesně
+to, co vyžaduje `@onlineapps/content-resolver` a za ním `@onlineapps/conn-base-storage`.
+Chybějící logger i logger neúplný padají hned v `getContentResolver()` a hláška
+jmenuje chybějící metodu; žádný `console` fallback neexistuje.
+
 ## Usage in Cookbook
 
 Helpers jsou k dispozici při resolvování template proměnných:
@@ -65,38 +74,39 @@ Helpers jsou k dispozici při resolvování template proměnných:
 
 ## Integration
 
-Tyto helpery jsou v `@onlineapps/cookbook-executor` zapojené **jako výchozí** —
-executor si je vyžádá sám a nic se předávat nemusí:
+Tenhle balíček se do běhu nezapojuje sám a nikdo ho v běhové cestě nevyžaduje
+přímo. Cesta je tříčlánková a jde vždy stejně:
+
+1. balíček je závislostí `@onlineapps/conn-orch-cookbook`, který ho re-exportuje
+   jako plochý klíč `templateHelpers`
+   (`shared/connector/conn-orch-cookbook/src/index.js`);
+2. `ServiceWrapper` injektuje **celý modul** `conn-orch-cookbook` do
+   orchestrátoru jako `config.cookbook`
+   (`shared/connector/service-wrapper/src/ServiceWrapper.js:1818`);
+3. `WorkflowOrchestrator` si helper vyzvedne při rozvíjení `{{helper(...)}}`
+   ve vstupu kroku:
 
 ```javascript
-const { CookbookExecutor } = require('@onlineapps/cookbook-executor');
+// shared/connector/conn-orch-orchestrator/src/WorkflowOrchestrator.js:786
+const helpers = this.cookbook?.templateHelpers || {};
+const helperFn = helpers[helperName];
 
-// helpers se neuvádí — executor použije tento balíček automaticky
-const executor = new CookbookExecutor(cookbook);
+if (typeof helperFn !== 'function') {
+  throw new Error(`[WorkflowOrchestrator] Unknown template helper '${helperName}' - Expected helper to exist in cookbook.templateHelpers`);
+}
 ```
 
-Volba `helpers` existuje jen jako **override** — když ji předáš, výchozí sada se
-nepoužije a platí výhradně to, co jsi předal (viz `cookbook-executor/src/executor.js`,
-`const helpers = options.helpers || templateHelpers`). Pokud chceš výchozí helpery
-zachovat a jen přidat vlastní, musíš je do override sady zahrnout — viz níže.
+Žádná volba `helpers` a žádný override neexistují: platí přesně to, co tenhle
+balíček exportuje. Neznámý helper je tvrdá chyba, ne prázdná hodnota.
 
-## Adding Custom Helpers
+Živý cookbook, který touhle cestou prochází:
+[`infra/api_doorman/cookbooks/tester-helpers.json`](../../../infra/api_doorman/cookbooks/tester-helpers.json)
+— volá `normalizeString`, `webalizeString`, `string2file` i `file2string`.
 
-You can combine global helpers with custom helpers:
+## Adding a Helper
 
-```javascript
-const templateHelpers = require('@onlineapps/cookbook-template-helpers');
-const customHelpers = require('./customHelpers');
-
-const allHelpers = {
-  ...templateHelpers,
-  ...customHelpers
-};
-
-const executor = new CookbookExecutor(cookbook, {
-  helpers: allHelpers
-});
-```
+Nový helper se přidá **do tohoto balíčku** (a vydá se nová verze) — jinak se
+k orchestrátoru nedostane, protože ten čte výhradně `cookbook.templateHelpers`.
 
 ## Helper Function Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/cookbook-template-helpers",
-  "version": "1.0.14",
+  "version": "2.0.0",
   "description": "Template helper functions for cookbook variable resolution - string2file, file2string, and more",
   "main": "src/index.js",
   "scripts": {
@@ -19,7 +19,7 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/content-resolver": "2.0.0"
+    "@onlineapps/content-resolver": "3.0.0"
   },
   "devDependencies": {
     "jest": "29.7.0"

package/src/helpers/fileHelpers.js

@@ -7,6 +7,10 @@
 
 const ContentResolver = require('@onlineapps/content-resolver');
 
+// The logger methods `ContentResolver` requires of the object this module hands
+// it — the order is the order the error message lists them in.
+const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
+
 /**
  * Normalize string: remove control/unsafe chars, keep letters (incl. diacritics), numbers,
  * whitespace and basic punctuation .,!?;:-_
@@ -66,8 +70,27 @@ function getContentResolver(helperContext) {
     helperContext.data?.step_id ||
     null;
 
-  if (!helperContext.logger || typeof helperContext.logger.warn !== 'function') {
-    throw new Error('[cookbook-template-helpers] Helper context logger is required - Expected logger with warn() method');
+  // The logger goes straight into `ContentResolver`, which demands all four
+  // methods (content-resolver src/index.js; conn-base-storage 3.0.0 behind it).
+  // Until 2026-09-03 only `warn()` was checked here, so a three-method logger
+  // passed this gate and failed one frame down — delayed validation, forbidden
+  // by architecture-principles.md §4. Owner confirmation:
+  // api/docs/governance/confirmations/connector-logger-contract.md 001.
+  if (!helperContext.logger) {
+    throw new Error(
+      '[cookbook-template-helpers] logger is required - Expected: a logger with info/warn/error/debug, '
+      + 'so the resolver this helper builds writes where the service writes. '
+      + 'Fix: pass context.logger (e.g. the logger your service already built).'
+    );
+  }
+
+  const missing = LOGGER_METHODS.filter((method) => typeof helperContext.logger[method] !== 'function');
+  if (missing.length > 0) {
+    throw new Error(
+      '[cookbook-template-helpers] logger is incomplete - Expected: info, warn, error, debug as functions; '
+      + `missing: ${missing.join(', ')}. `
+      + 'Fix: pass a logger implementing all four.'
+    );
   }
 
   return new ContentResolver({