@onlineapps/cookbook-template-helpers 1.0.1 → 1.0.3

package/README.md

@@ -15,104 +15,54 @@ Helper functions can be used in cookbook template variables using the syntax:
 {{helper_name(argument)}}
 ```
 
-Arguments can be template variables themselves:
-```
-{{helper_name(steps.step_id.output.field)}}
-```
-
 ## Available Helpers
 
-### string2file
-
-Converts string content or inline descriptor to file descriptor. Uploads content to MinIO storage.
+### normalizeString
+Removes nebezpečné / ne-print znaky, ponechá písmena (včetně diakritiky), čísla, mezery a základní interpunkci. Zachová diakritiku a case.
 
 **Signature:**
 ```javascript
-async function string2file(input, context)
+function normalizeString(value)
 ```
 
-**Parameters:**
-- `input` (string|Object) - String content or inline descriptor
-- `context` (Object) - Workflow context (for storage access)
+### webalizeString
+Normalizuje řetězec pro URL/slug: odstraní diakritiku, interpunkci, nahradí mezery pomlčkami, převede na lowercase, zkolabuje vícenásobné pomlčky.
 
-**Returns:**
-- `Promise<Object>` - File descriptor
-
-**Examples:**
-
-```json
-{
-  "input": {
-    "file": "{{string2file(steps.markdown.output.content)}}"
-  }
-}
+**Signature:**
+```javascript
+function webalizeString(value)
 ```
 
-```json
-{
-  "input": {
-    "file": "{{string2file('Hello world')}}"
-  }
-}
+### string2file
+Převede string nebo inline descriptor na file descriptor (přes ContentResolver). Ukládá do storage podle nastavení ContentResolveru.
+
+**Signature:**
+```javascript
+async function string2file(input, context)
 ```
 
 ### file2string
-
-Converts file descriptor to string. Downloads content from MinIO if needed.
+Převede file/inline descriptor na string (přes ContentResolver). File stáhne z MinIO, inline vrátí přímo.
 
 **Signature:**
 ```javascript
 async function file2string(descriptor, context)
 ```
 
-**Parameters:**
-- `descriptor` (Object|string) - File descriptor or string
-- `context` (Object) - Workflow context (for storage access)
-
-**Returns:**
-- `Promise<string>` - String content
-
-**Examples:**
+## Usage in Cookbook
 
+Helpers jsou k dispozici při resolvování template proměnných:
 ```json
 {
   "input": {
-    "markdown": "{{file2string(steps.pdf.output.file_descriptor)}}"
+    "title": "{{normalizeString(api_input.title)}}",
+    "slug": "{{webalizeString(api_input.title)}}",
+    "file": "{{string2file(api_input.content)}}",
+    "content": "{{file2string(steps.prepare.output.file_descriptor)}}"
   }
 }
 ```
 
-## Usage in Cookbook
-
-Helper functions are integrated into the cookbook executor. They are automatically available when resolving template variables.
-
-**Example cookbook:**
-
-```json
-{
-  "version": "2.0.0",
-  "steps": [
-    {
-      "step_id": "get_markdown",
-      "type": "task",
-      "service": "hello-service",
-      "operation": "generate-markdown",
-      "input": { "name": "Karel" }
-    },
-    {
-      "step_id": "create_pdf",
-      "type": "task",
-      "service": "pdfgen-service",
-      "operation": "md2pdf",
-      "depends_on": ["get_markdown"],
-      "input": {
-        "markdown": "{{file2string(steps.get_markdown.output.file_descriptor)}}"
-      }
-    }
-  ]
-}
-```
-
 ## Integration
 
 Helper functions are passed to the cookbook executor:
@@ -146,41 +96,13 @@ const executor = new CookbookExecutor(cookbook, {
 
 ## Helper Function Requirements
 
-- **Async**: All helpers must be async functions (return Promise)
-- **Context**: Helpers receive workflow context as last parameter
-- **Idempotent**: Same input should produce same output
-- **Error handling**: Should throw descriptive errors
+- **Deterministic**: Stejný vstup = stejný výstup
+- **Bez vedlejších efektů**: String helpery jsou čisté; file helpery používají ContentResolver
+- **Chyby**: Měly by být jasné a srozumitelné
 
 ## Dependencies
 
-- `@onlineapps/conn-base-storage` - For MinIO storage operations
-
-## Environment Variables
-
-Helper functions use the following environment variables for storage access:
-
-- `MINIO_HOST` - MinIO endpoint (default: `api_shared_storage`)
-- `MINIO_PORT` - MinIO port (default: `9000`)
-- `MINIO_ACCESS_KEY` - MinIO access key (default: `minioadmin`)
-- `MINIO_SECRET_KEY` - MinIO secret key (default: `minioadmin`)
-- `MINIO_USE_SSL` - Use SSL (default: `false`)
-
-## File Descriptor Format
-
-File descriptors have the following structure:
-
-```javascript
-{
-  _descriptor: true,
-  type: 'file',  // or 'inline'
-  storage_ref: 'minio://workflow/path/to/file',  // for type='file'
-  content: '...',  // for type='inline'
-  filename: 'document.txt',
-  content_type: 'text/plain',
-  size: 1234,
-  fingerprint: 'sha256...'
-}
-```
+- `@onlineapps/content-resolver` (pro string2file/file2string)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/cookbook-template-helpers",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Template helper functions for cookbook variable resolution - string2file, file2string, and more",
   "main": "src/index.js",
   "scripts": {
@@ -19,10 +19,10 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/conn-base-storage": "^1.0.0"
+    "@onlineapps/content-resolver": "1.1.6"
   },
   "devDependencies": {
-    "jest": "^29.7.0"
+    "jest": "29.7.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/helpers/fileHelpers.js

@@ -1,200 +1,131 @@
 'use strict';
 
 /**
- * File helper functions for cookbook template resolution
- * Converts between string content and file descriptors
+ * Helper functions for cookbook template resolution.
+ * Includes safe string normalization and descriptor/string conversions.
  */
 
-const StorageConnector = require('@onlineapps/conn-base-storage');
+const ContentResolver = require('@onlineapps/content-resolver');
 
 /**
- * Get storage instance from context or create new one
+ * Normalize string: remove control/unsafe chars, keep letters (incl. diacritics), numbers,
+ * whitespace and basic punctuation .,!?;:-_
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeString(value) {
+  if (value === null || value === undefined) return '';
+  const str = String(value);
+  // Allow common Latin ranges (including diacritics), numbers, whitespace and basic punctuation
+  const cleaned = str.replace(/[^\x20-\x7E\u00A0-\u024F\u1E00-\u1EFF\s\.\,\!\?\;\:\-\_]/g, '');
+  // Explicitly drop angle brackets to avoid HTML/script injection noise
+  return cleaned.replace(/[<>]/g, '');
+}
+
+/**
+ * Webalize string: normalize, strip diacritics, remove punctuation, lowercase, replace spaces with hyphens.
+ * @param {string} value
+ * @returns {string}
+ */
+function webalizeString(value) {
+  const normalized = normalizeString(value);
+  const noPunct = normalized.replace(/[\.\,\!\?\;\:]/g, '');
+  const withoutDiacritics = noPunct.normalize('NFD').replace(/\p{Diacritic}/gu, '');
+  const withHyphens = withoutDiacritics.trim().replace(/\s+/g, '-');
+  return withHyphens.toLowerCase().replace(/-+/g, '-');
+}
+
+/**
+ * Get ContentResolver instance (DI first, else new).
  * @private
- * @param {Object} context - Workflow context
- * @returns {Promise<Object>} Storage connector instance
  */
-async function getStorageFromContext(context) {
-  // If storage is already in context, use it
-  if (context._storage) {
-    return context._storage;
+function getContentResolver(helperContext) {
+  if (!helperContext || typeof helperContext !== 'object') {
+    throw new Error('[cookbook-template-helpers] Helper context is required');
+  }
+
+  if (
+    helperContext.contentResolver &&
+    typeof helperContext.contentResolver.getAsString === 'function' &&
+    typeof helperContext.contentResolver.createDescriptor === 'function'
+  ) {
+    return helperContext.contentResolver;
   }
 
-  // Otherwise create new storage instance
-  const storage = new StorageConnector({
-    endpoint: process.env.MINIO_HOST || 'api_shared_storage',
-    port: parseInt(process.env.MINIO_PORT || '9000', 10),
-    accessKey: process.env.MINIO_ACCESS_KEY || 'minioadmin',
-    secretKey: process.env.MINIO_SECRET_KEY || 'minioadmin',
-    useSSL: process.env.MINIO_USE_SSL === 'true'
-  });
-
-  // Cache in context for reuse
-  context._storage = storage;
-  return storage;
+  const workflow_id =
+    helperContext.workflow_id ||
+    helperContext.data?.variables?.workflow_id ||
+    helperContext.data?.workflow_id ||
+    null;
+
+  const step_id =
+    helperContext.step_id ||
+    helperContext.data?.variables?.step_id ||
+    helperContext.data?.step_id ||
+    null;
+
+  return new ContentResolver({ context: { workflow_id, step_id } });
 }
 
 /**
- * Convert string or inline descriptor to file descriptor
- * Uploads content to MinIO and returns file descriptor
- * 
- * @param {string|Object} input - String content or inline descriptor
- * @param {Object} context - Workflow context (for storage access)
- * @returns {Promise<Object>} File descriptor
- * 
- * @example
- * // String input
- * const descriptor = await string2file('Hello world', context);
- * 
- * @example
- * // Inline descriptor input
- * const descriptor = await string2file({
- *   _descriptor: true,
- *   type: 'inline',
- *   content: 'Hello world',
- *   filename: 'greeting.txt'
- * }, context);
+ * Convert string or inline descriptor to file descriptor (uploads via ContentResolver).
+ * @param {string|Object} input
+ * @param {Object} context
+ * @returns {Promise<Object>}
  */
 async function string2file(input, context) {
-  if (!input) {
+  if (input === null || input === undefined) {
     throw new Error('[string2file] Input is required');
   }
 
-  // Pokud už je file descriptor, vrať ho
-  if (input._descriptor && input.type === 'file') {
+  // Already a file descriptor
+  if (input && input._descriptor === true && input.type === 'file') {
     return input;
   }
 
-  // Pokud je inline descriptor, převeď na file
-  if (input._descriptor && input.type === 'inline') {
+  const resolver = getContentResolver(context);
+
+  // Inline descriptor -> file
+  if (input && input._descriptor === true && input.type === 'inline') {
     const content = input.content;
     if (typeof content !== 'string') {
       throw new Error('[string2file] Inline descriptor content must be a string');
     }
-
-    const storage = await getStorageFromContext(context);
-    const encoding = input.encoding || 'utf-8';
-    const buffer = Buffer.from(content, encoding);
-
-    // Upload do MinIO
-    const workflowId = context.workflow_id || context.workflowId || 'temp';
-    const stepId = context.step_id || context.stepId || 'helpers';
-    const pathPrefix = `helpers/${workflowId}/${stepId}`;
-
-    const result = await storage.uploadWithFingerprint(
-      'workflow',
-      buffer,
-      pathPrefix
-    );
-
-    return {
-      _descriptor: true,
-      type: 'file',
-      storage_ref: `minio://workflow/${result.path}`,
-      filename: input.filename || 'content.txt',
-      content_type: input.content_type || 'text/plain',
-      size: buffer.length,
-      fingerprint: result.fingerprint
-    };
+    return await resolver.createDescriptor(content, {
+      filename: input.filename,
+      content_type: input.content_type,
+      context: { workflow_id: context.workflow_id, step_id: context.step_id },
+      forceFile: true
+    });
   }
 
-  // Pokud je string, vytvoř file descriptor
+  // Raw string -> file descriptor
   if (typeof input === 'string') {
-    const storage = await getStorageFromContext(context);
-    const buffer = Buffer.from(input, 'utf-8');
-
-    const workflowId = context.workflow_id || context.workflowId || 'temp';
-    const stepId = context.step_id || context.stepId || 'helpers';
-    const pathPrefix = `helpers/${workflowId}/${stepId}`;
-
-    const result = await storage.uploadWithFingerprint(
-      'workflow',
-      buffer,
-      pathPrefix
-    );
-
-    return {
-      _descriptor: true,
-      type: 'file',
-      storage_ref: `minio://workflow/${result.path}`,
+    return await resolver.createDescriptor(input, {
       filename: 'content.txt',
       content_type: 'text/plain',
-      size: buffer.length,
-      fingerprint: result.fingerprint
-    };
+      context: { workflow_id: context.workflow_id, step_id: context.step_id },
+      forceFile: true
+    });
   }
 
   throw new Error('[string2file] Invalid input - expected string or descriptor');
 }
 
 /**
- * Convert file descriptor to string
- * Downloads content from MinIO if needed
- * 
- * @param {Object|string} descriptor - File descriptor or string
- * @param {Object} context - Workflow context (for storage access)
- * @returns {Promise<string>} String content
- * 
- * @example
- * // File descriptor input
- * const content = await file2string({
- *   _descriptor: true,
- *   type: 'file',
- *   storage_ref: 'minio://workflow/path/to/file',
- *   fingerprint: 'abc123...'
- * }, context);
- * 
- * @example
- * // Inline descriptor input
- * const content = await file2string({
- *   _descriptor: true,
- *   type: 'inline',
- *   content: 'Hello world'
- * }, context);
+ * Convert file descriptor to string (downloads via ContentResolver).
+ * @param {Object|string} descriptor
+ * @param {Object} context
+ * @returns {Promise<string>}
  */
 async function file2string(descriptor, context) {
-  // Pokud není descriptor, vrať jak je (pokud je string)
-  if (!descriptor || !descriptor._descriptor) {
-    if (typeof descriptor === 'string') {
-      return descriptor;
-    }
-    return String(descriptor || '');
-  }
-
-  // Pokud je inline, vrať content
-  if (descriptor.type === 'inline') {
-    return descriptor.content || '';
-  }
-
-  // Pokud je file, stáhni z MinIO
-  if (descriptor.type === 'file') {
-    if (!descriptor.storage_ref) {
-      throw new Error('[file2string] File descriptor missing storage_ref');
-    }
-
-    const storage = await getStorageFromContext(context);
-    
-    // Parse storage_ref: minio://workflow/path/to/file
-    const match = descriptor.storage_ref.match(/^minio:\/\/([^\/]+)\/(.+)$/);
-    if (!match) {
-      throw new Error(`[file2string] Invalid storage_ref format: ${descriptor.storage_ref}`);
-    }
-
-    const [, bucket, path] = match;
-    
-    // Download with fingerprint verification
-    const content = await storage.downloadWithVerification(
-      bucket,
-      path,
-      descriptor.fingerprint
-    );
-
-    return content.toString('utf-8');
-  }
-
-  throw new Error(`[file2string] Invalid descriptor type: ${descriptor.type}`);
+  const resolver = getContentResolver(context);
+  return await resolver.getAsString(descriptor);
 }
 
 module.exports = {
+  normalizeString,
+  webalizeString,
   string2file,
   file2string
 };

package/src/index.js

@@ -15,6 +15,8 @@
 const fileHelpers = require('./helpers/fileHelpers');
 
 module.exports = {
+  normalizeString: fileHelpers.normalizeString,
+  webalizeString: fileHelpers.webalizeString,
   string2file: fileHelpers.string2file,
   file2string: fileHelpers.file2string
 };