@output.ai/core 0.3.0-dev.pr263-a59dd0e → 0.3.0-dev.pr263-8f8e94a

package/bin/worker.sh

@@ -23,4 +23,4 @@ sdk_dir="$(dirname "$script_dir")"
 
 cd ${sdk_dir}
 
-exec npm run worker -- ${invocation_dir} "${@:2}"  # Pass remaining args
+exec node "${sdk_dir}/src/worker/index.js" "${invocation_dir}" "${@:2}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.3.0-dev.pr263-a59dd0e",
+  "version": "0.3.0-dev.pr263-8f8e94a",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/consts.js

@@ -1,7 +1,7 @@
 export const ACTIVITY_SEND_HTTP_REQUEST = '__internal#sendHttpRequest';
 export const ACTIVITY_GET_TRACE_DESTINATIONS = '__internal#getTraceDestinations';
 export const METADATA_ACCESS_SYMBOL = Symbol( '__metadata' );
-export const SHARED_STEP_PREFIX = '__shared#';
+export const SHARED_STEP_PREFIX = '$shared';
 export const WORKFLOWS_INDEX_FILENAME = '__workflows_entrypoint.js';
 export const ACTIVITY_OPTIONS_FILENAME = '__activity_options.js';
 export const WORKFLOW_CATALOG = '$catalog';

package/src/interface/evaluator.js

@@ -81,6 +81,7 @@ export class EvaluationStringResult extends EvaluationResult {
    * @param {number} args.confidence - The confidence on the evaluation
    * @param {string} [args.reasoning] - The reasoning behind the result
    */
+  // eslint-disable-next-line no-useless-constructor
   constructor( args ) {
     super( args );
   }
@@ -103,6 +104,7 @@ export class EvaluationBooleanResult extends EvaluationResult {
    * @param {number} args.confidence - The confidence on the evaluation
    * @param {string} [args.reasoning] - The reasoning behind the result
    */
+  // eslint-disable-next-line no-useless-constructor
   constructor( args ) {
     super( args );
   }
@@ -125,6 +127,7 @@ export class EvaluationNumberResult extends EvaluationResult {
    * @param {number} args.confidence - The confidence on the evaluation
    * @param {string} [args.reasoning] - The reasoning behind the result
    */
+  // eslint-disable-next-line no-useless-constructor
   constructor( args ) {
     super( args );
   }

package/src/interface/workflow.js

@@ -3,7 +3,7 @@ import { proxyActivities, inWorkflowContext, executeChild, workflowInfo, uuid4,
 import { validateWorkflow } from './validations/static.js';
 import { validateWithSchema } from './validations/runtime.js';
 import { SHARED_STEP_PREFIX, ACTIVITY_GET_TRACE_DESTINATIONS } from '#consts';
-import { deepMerge, mergeActivityOptions, resolveInvocationDir, setMetadata } from '#utils';
+import { deepMerge, mergeActivityOptions, setMetadata } from '#utils';
 import { FatalError, ValidationError } from '#errors';
 
 /**
@@ -51,7 +51,6 @@ const defaultActivityOptions = {
 
 export function workflow( { name, description, inputSchema, outputSchema, fn, options } ) {
   validateWorkflow( { name, description, inputSchema, outputSchema, fn, options } );
-  const workflowPath = resolveInvocationDir();
 
   const activityOptions = mergeActivityOptions( defaultActivityOptions, options );
   const steps = proxyActivities( activityOptions );
@@ -99,9 +98,9 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
 
     // binds the methods called in the code that Webpack loader will add, they will exposed via "this"
     const output = await fn.call( {
-      invokeStep: async ( stepName, input, options ) => steps[`${workflowPath}#${stepName}`]( input, options ),
+      invokeStep: async ( stepName, input, options ) => steps[`${name}#${stepName}`]( input, options ),
       invokeSharedStep: async ( stepName, input, options ) => steps[`${SHARED_STEP_PREFIX}#${stepName}`]( input, options ),
-      invokeEvaluator: async ( evaluatorName, input, options ) => steps[`${workflowPath}#${evaluatorName}`]( input, options ),
+      invokeEvaluator: async ( evaluatorName, input, options ) => steps[`${name}#${evaluatorName}`]( input, options ),
 
       /**
        * Start a child workflow

package/src/worker/catalog_workflow/workflow.js

@@ -1,4 +1,4 @@
-import { defineQuery, setHandler } from '@temporalio/workflow';
+import { defineQuery, setHandler, condition } from '@temporalio/workflow';
 
 /**
  * This is a special workflow, unique to each worker, which holds the meta information of all other workflows in that worker.
@@ -9,5 +9,6 @@ import { defineQuery, setHandler } from '@temporalio/workflow';
  */
 export default async function catalogWorkflow( catalog ) {
   setHandler( defineQuery( 'get' ), () => catalog );
-  await new Promise( () => {} ); // stay alive
+  // Wait indefinitely but remain responsive to workflow cancellation
+  await condition( () => false );
 };

package/src/worker/index.js

@@ -18,7 +18,7 @@ const callerDir = process.argv[2];
   const workflows = await loadWorkflows( callerDir );
 
   console.log( '[Core]', 'Loading activities...', { callerDir } );
-  const activities = await loadActivities( callerDir );
+  const activities = await loadActivities( callerDir, workflows );
 
   console.log( '[Core]', 'Creating worker entry point...' );
   const workflowsPath = createWorkflowsEntryPoint( workflows );
@@ -56,5 +56,39 @@ const callerDir = process.argv[2];
   } );
 
   console.log( '[Core]', 'Running worker...' );
-  worker.run();
-} )();
+
+  // FORCE_QUIT_GRACE_MS delays the second instance of a shutdown command.
+  // If running output-worker directly with npx, 2 signals are recieved in
+  // rapid succession, and users see the force quit message.
+  const FORCE_QUIT_GRACE_MS = 1000;
+  const state = { isShuttingDown: false, shutdownStartedAt: null };
+
+  const shutdown = signal => {
+    if ( state.isShuttingDown ) {
+      const elapsed = Date.now() - state.shutdownStartedAt;
+      if ( elapsed < FORCE_QUIT_GRACE_MS ) {
+        return; // ignore rapid duplicate signals
+      }
+      process.stderr.write( '[Core] Force quitting...\n' );
+      process.exit( 1 );
+    }
+    state.isShuttingDown = true;
+    state.shutdownStartedAt = Date.now();
+    process.stderr.write( `[Core] Received ${signal}, shutting down...\n` );
+    worker.shutdown();
+  };
+
+  process.on( 'SIGTERM', () => shutdown( 'SIGTERM' ) );
+  process.on( 'SIGINT', () => shutdown( 'SIGINT' ) );
+
+  await worker.run();
+  process.stderr.write( '[Core] Worker stopped.\n' );
+
+  await connection.close();
+  process.stderr.write( '[Core] Connection closed.\n' );
+
+  process.exit( 0 );
+} )().catch( error => {
+  process.stderr.write( `[Core] Fatal error: ${error.message}\n` );
+  process.exit( 1 );
+} );

package/src/worker/loader.js

@@ -3,7 +3,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { EOL } from 'node:os';
 import { fileURLToPath } from 'url';
 import { getTraceDestinations, sendHttpRequest } from '#internal_activities';
-import { importComponents } from './loader_tools.js';
+import { importComponents, staticMatchers, activityMatchersBuilder } from './loader_tools.js';
 import {
   ACTIVITY_SEND_HTTP_REQUEST,
   ACTIVITY_OPTIONS_FILENAME,
@@ -27,24 +27,61 @@ const writeActivityOptionsFile = map => {
 };
 
 /**
- * Builds a map of activities, where the key is their path and name and the value is the function
+ * Creates the activity key that will identify it on Temporal.
  *
- * @param {string} target
+ * It composes it using a namespace and the name of the activity.
+ *
+ * No two activities with the same name can exist on the same namespace.
+ *
+ * @param {object} options
+ * @param {string} namespace
+ * @param {string} activityName
+ * @returns {string} key
+ */
+const generateActivityKey = ( { namespace, activityName } ) => `${namespace}#${activityName}`;
+
+/**
+ * Load activities:
+ *
+ * - Scans activities based on workflows, using each workflow folder as a point to lookup for steps, evaluators files;
+ * - Scans shared activities in the rootDir;
+ * - Loads internal activities as well;
+ *
+ * Builds a map of activities, where they is generated according to the type of activity and the value is the function itself and return it.
+ * - Shared activity keys have a common prefix followed by the activity name;
+ * - Internal activities are registered with a fixed key;
+ * - Workflow activities keys are composed using the workflow name and the activity name;
+ *
+ * @param {string} rootDir
+ * @param {object[]} workflows
  * @returns {object}
  */
-export async function loadActivities( target ) {
+export async function loadActivities( rootDir, workflows ) {
   const activities = {};
   const activityOptionsMap = {};
-  for await ( const { fn, metadata, path, isShared } of importComponents( target, [ 'steps.js', 'evaluators.js' ] ) ) {
-    const prefix = isShared ? SHARED_STEP_PREFIX : dirname( path );
 
-    console.log( '[Core.Scanner]', 'Component loaded:', metadata.type, metadata.name, 'at', path );
-    activities[`${prefix}#${metadata.name}`] = fn;
-    if ( metadata.options ) {
-      activityOptionsMap[`${prefix}#${metadata.name}`] = metadata.options;
+  // Load workflow based activities
+  for ( const { path: workflowPath, name: workflowName } of workflows ) {
+    const dir = dirname( workflowPath );
+    for await ( const { fn, metadata, path } of importComponents( dir, Object.values( activityMatchersBuilder( dir ) ) ) ) {
+      console.log( '[Core.Scanner]', 'Component loaded:', metadata.type, metadata.name, 'at', path );
+      // Activities loaded from a workflow path will use the workflow name as a namespace, which is unique across the platform, avoiding collision
+      const activityKey = generateActivityKey( { namespace: workflowName, activityName: metadata.name } );
+      activities[activityKey] = fn;
+      // propagate the custom options set on the step()/evaluator() constructor
+      activityOptionsMap[activityKey] = metadata.options ?? undefined;
     }
   }
 
+  // Load shared activities/evaluators
+  for await ( const { fn, metadata, path } of importComponents( rootDir, [ staticMatchers.sharedStepsDir, staticMatchers.sharedEvaluatorsDir ] ) ) {
+    console.log( '[Core.Scanner]', 'Component loaded: shared ', metadata.type, metadata.name, 'at', path );
+    // The namespace for shared activities is fixed
+    const activityKey = generateActivityKey( { namespace: SHARED_STEP_PREFIX, activityName: metadata.name } );
+    activities[activityKey] = fn;
+    activityOptionsMap[activityKey] = metadata.options ?? undefined;
+  }
+
   // writes down the activity option overrides
   writeActivityOptionsFile( activityOptionsMap );
 
@@ -55,14 +92,19 @@ export async function loadActivities( target ) {
 };
 
 /**
- * Builds an array of workflow objects
+ * Scan and find workflow.js files and import them.
+ *
+ * Creates an array containing their metadata and path and return it.
  *
- * @param {string} target
+ * @param {string} rootDir
  * @returns {object[]}
  */
-export async function loadWorkflows( target ) {
+export async function loadWorkflows( rootDir ) {
   const workflows = [];
-  for await ( const { metadata, path } of importComponents( target, [ 'workflow.js' ] ) ) {
+  for await ( const { metadata, path } of importComponents( rootDir, [ staticMatchers.workflowFile ] ) ) {
+    if ( staticMatchers.workflowPathHasShared( path ) ) {
+      throw new Error( 'Workflow directory can\'t be named "shared"' );
+    }
     console.log( '[Core.Scanner]', 'Workflow loaded:', metadata.name, 'at', path );
     workflows.push( { ...metadata, path } );
   }
@@ -70,7 +112,7 @@ export async function loadWorkflows( target ) {
 };
 
 /**
- * Creates a temporary index file importing all workflows
+ * Creates a temporary index file importing all workflows for Temporal.
  *
  * @param {object[]} workflows
  * @returns

package/src/worker/loader.spec.js

@@ -6,7 +6,7 @@ vi.mock( '#consts', () => ( {
   WORKFLOWS_INDEX_FILENAME: '__workflows_entrypoint.js',
   WORKFLOW_CATALOG: 'catalog',
   ACTIVITY_OPTIONS_FILENAME: '__activity_options.js',
-  SHARED_STEP_PREFIX: '/shared'
+  SHARED_STEP_PREFIX: '$shared'
 } ) );
 
 const sendHttpRequestMock = vi.fn();
@@ -17,7 +17,10 @@ vi.mock( '#internal_activities', () => ( {
 } ) );
 
 const importComponentsMock = vi.fn();
-vi.mock( './loader_tools.js', () => ( { importComponents: importComponentsMock } ) );
+vi.mock( './loader_tools.js', async importOriginal => {
+  const actual = await importOriginal();
+  return { ...actual, importComponents: importComponentsMock };
+} );
 
 const mkdirSyncMock = vi.fn();
 const writeFileSyncMock = vi.fn();
@@ -34,12 +37,16 @@ describe( 'worker/loader', () => {
   it( 'loadActivities returns map including system activity and writes options file', async () => {
     const { loadActivities } = await import( './loader.js' );
 
+    // First call: workflow directory scan
     importComponentsMock.mockImplementationOnce( async function *() {
       yield { fn: () => {}, metadata: { name: 'Act1', options: { retry: { maximumAttempts: 3 } } }, path: '/a/steps.js' };
     } );
+    // Second call: shared activities scan (no results)
+    importComponentsMock.mockImplementationOnce( async function *() {} );
 
-    const activities = await loadActivities( '/root' );
-    expect( activities['/a#Act1'] ).toBeTypeOf( 'function' );
+    const workflows = [ { name: 'A', path: '/a/workflow.js' } ];
+    const activities = await loadActivities( '/root', workflows );
+    expect( activities['A#Act1'] ).toBeTypeOf( 'function' );
     expect( activities['__internal#sendHttpRequest'] ).toBe( sendHttpRequestMock );
 
     // options file written with the collected map
@@ -48,32 +55,11 @@ describe( 'worker/loader', () => {
     expect( writtenPath ).toMatch( /temp\/__activity_options\.js$/ );
     expect( contents ).toContain( 'export default' );
     expect( JSON.parse( contents.replace( /^export default\s*/, '' ).replace( /;\s*$/, '' ) ) ).toEqual( {
-      '/a#Act1': { retry: { maximumAttempts: 3 } }
+      'A#Act1': { retry: { maximumAttempts: 3 } }
     } );
     expect( mkdirSyncMock ).toHaveBeenCalled();
   } );
 
-  it( 'loadActivities uses SHARED_STEP_PREFIX for components with isShared flag', async () => {
-    const { loadActivities } = await import( './loader.js' );
-
-    importComponentsMock.mockImplementationOnce( async function *() {
-      yield { fn: () => 'local', metadata: { name: 'LocalStep' }, path: '/workflows/example/steps.js', isShared: false };
-      yield { fn: () => 'shared', metadata: { name: 'SharedStep' }, path: '/shared/steps/tools.js', isShared: true };
-    } );
-
-    const activities = await loadActivities( '/root' );
-
-    // Local step uses dirname as prefix
-    expect( activities['/workflows/example#LocalStep'] ).toBeTypeOf( 'function' );
-
-    // Shared step uses SHARED_STEP_PREFIX ('/shared' from mock)
-    expect( activities['/shared#SharedStep'] ).toBeTypeOf( 'function' );
-
-    // Verify they're different functions
-    expect( activities['/workflows/example#LocalStep']() ).toBe( 'local' );
-    expect( activities['/shared#SharedStep']() ).toBe( 'shared' );
-  } );
-
   it( 'loadWorkflows returns array of workflows with metadata', async () => {
     const { loadWorkflows } = await import( './loader.js' );
 
@@ -98,4 +84,98 @@ describe( 'worker/loader', () => {
     expect( contents ).toContain( 'export { default as catalog }' );
     expect( mkdirSyncMock ).toHaveBeenCalledTimes( 1 );
   } );
+
+  it( 'loadActivities uses folder-based matchers for steps/evaluators and shared', async () => {
+    const { loadActivities } = await import( './loader.js' );
+    // First call (workflow dir): no results
+    importComponentsMock.mockImplementationOnce( async function *() {} );
+    // Second call (shared): no results
+    importComponentsMock.mockImplementationOnce( async function *() {} );
+
+    const workflows = [ { name: 'A', path: '/a/workflow.js' } ];
+    await loadActivities( '/root', workflows );
+
+    // First invocation should target the workflow directory with folder/file matchers
+    expect( importComponentsMock ).toHaveBeenCalledTimes( 2 );
+    const [ firstDir, firstMatchers ] = importComponentsMock.mock.calls[0];
+    expect( firstDir ).toBe( '/a' );
+    expect( Array.isArray( firstMatchers ) ).toBe( true );
+    // Should match folder-based steps and evaluators files
+    expect( firstMatchers.some( fn => fn( '/a/steps/foo.js' ) ) ).toBe( true );
+    expect( firstMatchers.some( fn => fn( '/a/evaluators/bar.js' ) ) ).toBe( true );
+    // And also direct file names
+    expect( firstMatchers.some( fn => fn( '/a/steps.js' ) ) ).toBe( true );
+    expect( firstMatchers.some( fn => fn( '/a/evaluators.js' ) ) ).toBe( true );
+
+    // Second invocation should target root with shared matchers
+    const [ secondDir, secondMatchers ] = importComponentsMock.mock.calls[1];
+    expect( secondDir ).toBe( '/root' );
+    expect( secondMatchers.some( fn => fn( '/root/shared/steps/baz.js' ) ) ).toBe( true );
+    expect( secondMatchers.some( fn => fn( '/root/shared/evaluators/qux.js' ) ) ).toBe( true );
+  } );
+
+  it( 'loadActivities includes nested workflow steps and shared evaluators', async () => {
+    const { loadActivities } = await import( './loader.js' );
+    // Workflow dir scan returns a nested step
+    importComponentsMock.mockImplementationOnce( async function *() {
+      yield { fn: () => {}, metadata: { name: 'ActNested' }, path: '/a/steps/foo.js' };
+    } );
+    // Shared scan returns a shared evaluator
+    importComponentsMock.mockImplementationOnce( async function *() {
+      yield { fn: () => {}, metadata: { name: 'SharedEval' }, path: '/root/shared/evaluators/bar.js' };
+    } );
+
+    const workflows = [ { name: 'A', path: '/a/workflow.js' } ];
+    const activities = await loadActivities( '/root', workflows );
+    expect( activities['A#ActNested'] ).toBeTypeOf( 'function' );
+    expect( activities['$shared#SharedEval'] ).toBeTypeOf( 'function' );
+  } );
+
+  it( 'loadWorkflows throws when workflow is under shared directory', async () => {
+    const { loadWorkflows } = await import( './loader.js' );
+    importComponentsMock.mockImplementationOnce( async function *() {
+      yield { metadata: { name: 'Invalid' }, path: '/root/shared/workflow.js' };
+    } );
+    await expect( loadWorkflows( '/root' ) ).rejects.toThrow( 'Workflow directory can\'t be named \"shared\"' );
+  } );
+
+  it( 'collects workflow nested steps and evaluators across multiple subfolders', async () => {
+    const { loadActivities } = await import( './loader.js' );
+    // Workflow dir scan returns nested steps and evaluators
+    importComponentsMock.mockImplementationOnce( async function *() {
+      yield { fn: () => {}, metadata: { name: 'StepPrimary' }, path: '/a/steps/primary/foo.js' };
+      yield { fn: () => {}, metadata: { name: 'StepSecondary' }, path: '/a/steps/secondary/bar.js' };
+      yield { fn: () => {}, metadata: { name: 'EvalPrimary' }, path: '/a/evaluators/primary/baz.js' };
+      yield { fn: () => {}, metadata: { name: 'EvalSecondary' }, path: '/a/evaluators/secondary/qux.js' };
+    } );
+    // Shared scan returns nothing for this test
+    importComponentsMock.mockImplementationOnce( async function *() {} );
+
+    const workflows = [ { name: 'A', path: '/a/workflow.js' } ];
+    const activities = await loadActivities( '/root', workflows );
+    expect( activities['A#StepPrimary'] ).toBeTypeOf( 'function' );
+    expect( activities['A#StepSecondary'] ).toBeTypeOf( 'function' );
+    expect( activities['A#EvalPrimary'] ).toBeTypeOf( 'function' );
+    expect( activities['A#EvalSecondary'] ).toBeTypeOf( 'function' );
+  } );
+
+  it( 'collects shared nested steps and evaluators across multiple subfolders', async () => {
+    const { loadActivities } = await import( './loader.js' );
+    // Workflow dir scan returns nothing for this test
+    importComponentsMock.mockImplementationOnce( async function *() {} );
+    // Shared scan returns nested steps and evaluators
+    importComponentsMock.mockImplementationOnce( async function *() {
+      yield { fn: () => {}, metadata: { name: 'SharedStepPrimary' }, path: '/root/shared/steps/primary/a.js' };
+      yield { fn: () => {}, metadata: { name: 'SharedStepSecondary' }, path: '/root/shared/steps/secondary/b.js' };
+      yield { fn: () => {}, metadata: { name: 'SharedEvalPrimary' }, path: '/root/shared/evaluators/primary/c.js' };
+      yield { fn: () => {}, metadata: { name: 'SharedEvalSecondary' }, path: '/root/shared/evaluators/secondary/d.js' };
+    } );
+
+    const workflows = [ { name: 'A', path: '/a/workflow.js' } ];
+    const activities = await loadActivities( '/root', workflows );
+    expect( activities['$shared#SharedStepPrimary'] ).toBeTypeOf( 'function' );
+    expect( activities['$shared#SharedStepSecondary'] ).toBeTypeOf( 'function' );
+    expect( activities['$shared#SharedEvalPrimary'] ).toBeTypeOf( 'function' );
+    expect( activities['$shared#SharedEvalSecondary'] ).toBeTypeOf( 'function' );
+  } );
 } );

package/src/worker/loader_tools.js

@@ -1,4 +1,4 @@
-import { resolve } from 'path';
+import { resolve, sep } from 'path';
 import { pathToFileURL } from 'url';
 import { METADATA_ACCESS_SYMBOL } from '#consts';
 import { readdirSync } from 'fs';
@@ -7,59 +7,23 @@ import { readdirSync } from 'fs';
  * @typedef {object} CollectedFile
  * @property {string} path - The file path
  * @property {string} url - The resolved url of the file, ready to be imported
- * @property {boolean} [isShared] - Whether this file is in a shared/steps/ directory
  */
 /**
  * @typedef {object} Component
  * @property {Function} fn - The loaded component function
  * @property {object} metadata - Associated metadata with the component
- * @property {string} path - The file path of the component
- * @property {boolean} [isShared] - Whether this component is from a shared/steps/ directory
+ * @property {string} path - Associated metadata with the component
  */
 
 /**
- * Check if the search is targeting step or evaluator files.
- * @param {string[]} filenames - The filenames being searched for.
- * @returns {boolean} True if searching for steps.js or evaluators.js.
- */
-const isSearchingForStepFiles = filenames =>
-  filenames.includes( 'steps.js' ) || filenames.includes( 'evaluators.js' );
-
-/**
- * Check if a directory is a shared steps directory.
- * @param {string} dirName - The directory name.
- * @param {string} parentPath - The parent path.
- * @returns {boolean} True if this is a shared/steps directory.
- */
-const isSharedStepsDirectory = ( dirName, parentPath ) =>
-  dirName === 'steps' && parentPath.endsWith( '/shared' );
-
-/**
- * Collect all .js files from a shared steps directory.
- * @param {string} dirPath - The directory path.
- * @param {CollectedFile[]} collection - The collection to add files to.
- */
-const collectSharedStepsFiles = ( dirPath, collection ) => {
-  for ( const entry of readdirSync( dirPath, { withFileTypes: true } ) ) {
-    if ( entry.isFile() && entry.name.endsWith( '.js' ) ) {
-      const filePath = resolve( dirPath, entry.name );
-      collection.push( {
-        path: filePath,
-        url: pathToFileURL( filePath ).href,
-        isShared: true
-      } );
-    }
-  }
-};
-
-/**
- * Recursive traverse directories looking for files with given name.
+ * Recursive traverse directories collection files with paths that match one of the given matches.
  *
  * @param {string} path - The path to scan
- * @param {string[]} filenames  - The filenames to look for
+ * @param {function[]} matchers - Boolean functions to match files to add to collection
  * @returns {CollectedFile[]} An array containing the collected files
- * */
-const findByNameRecursively = ( parentPath, filenames, collection = [], ignoreDirNames = [ 'vendor', 'node_modules' ] ) => {
+ */
+const findByNameRecursively = ( parentPath, matchers, ignoreDirNames = [ 'vendor', 'node_modules' ] ) => {
+  const collection = [];
   for ( const entry of readdirSync( parentPath, { withFileTypes: true } ) ) {
     if ( ignoreDirNames.includes( entry.name ) ) {
       continue;
@@ -67,12 +31,8 @@ const findByNameRecursively = ( parentPath, filenames, collection = [], ignoreDi
 
     const path = resolve( parentPath, entry.name );
     if ( entry.isDirectory() ) {
-      if ( isSharedStepsDirectory( entry.name, parentPath ) && isSearchingForStepFiles( filenames ) ) {
-        collectSharedStepsFiles( path, collection );
-      } else {
-        findByNameRecursively( path, filenames, collection, ignoreDirNames );
-      }
-    } else if ( filenames.includes( entry.name ) ) {
+      collection.push( ...findByNameRecursively( path, matchers ) );
+    } else if ( matchers.some( m => m( path ) ) ) {
       collection.push( { path, url: pathToFileURL( path ).href } );
     }
   }
@@ -81,24 +41,92 @@ const findByNameRecursively = ( parentPath, filenames, collection = [], ignoreDi
 };
 
 /**
- * For each path, dynamic import it, and for each exported component with metadata (step, workflow), yields it.
+ * Scan a path for files testing each path against a matching function.
+ *
+ * For each file found, dynamic import it and for each exports on that file, yields it.
+ *
+ * @remarks
+ * - Only yields exports that have the METADATA_ACCESS_SYMBOL, as they are output components (steps, evaluators, etc).
  *
  * @generator
  * @async
  * @function importComponents
  * @param {string} target - Place to look for files
- * @param {string[]} filenames - File names to load recursively from target
+ * @param {function[]} matchers - Boolean functions to match files
  * @yields {Component}
  */
-export async function *importComponents( target, filenames ) {
-  for ( const { url, path, isShared } of findByNameRecursively( target, filenames ) ) {
+export async function *importComponents( target, matchers ) {
+  for ( const { url, path } of findByNameRecursively( target, matchers ) ) {
     const imported = await import( url );
     for ( const fn of Object.values( imported ) ) {
       const metadata = fn[METADATA_ACCESS_SYMBOL];
       if ( !metadata ) {
         continue;
       }
-      yield { fn, metadata, path, isShared };
+      yield { fn, metadata, path };
     }
   }
 };
+
+/**
+ * Returns matchers that need to be built using a relative path
+ *
+ * @param {string} path
+ * @returns {object} The object containing the matchers
+ */
+export const activityMatchersBuilder = path => ( {
+  /**
+   * Matches a file called steps.js, located at the path
+   * @param {string} path - Path to test
+   * @returns {boolean}
+   */
+  stepsFile: v => v === `${path}${sep}steps.js`,
+  /**
+   * Matches a file called evaluators.js, located at the path
+   * @param {string} path - Path to test
+   * @returns {boolean}
+   */
+  evaluatorsFile: v => v === `${path}${sep}evaluators.js`,
+  /**
+   * Matches all files on any levels inside a folder called steps/, located at the path
+   * @param {string} path - Path to test
+   * @returns {boolean}
+   */
+  stepsDir: v => v.startsWith( `${path}${sep}steps${sep}` ),
+  /**
+   * Matches all files on any levels inside a folder called evaluators/, located at the path
+   * @param {string} path - Path to test
+   * @returns {boolean}
+   */
+  evaluatorsDir: v => v.startsWith( `${path}${sep}evaluators${sep}` )
+} );
+
+/**
+ * Matchers that can be used to access conditions without initializing them
+ */
+export const staticMatchers = {
+  /**
+   * Matches a workflow.js file
+   * @param {string} path - Path to test
+   * @returns {boolean}
+   */
+  workflowFile: v => v.endsWith( `${sep}workflow.js` ),
+  /**
+   * Matches a workflow.js that is inside a shared folder: eg foo/shared/workflow.js
+   * @param {string} path - Path to test
+   * @returns {boolean}
+   */
+  workflowPathHasShared: v => v.endsWith( `${sep}shared${sep}workflow.js` ),
+  /**
+   * Matches the shared folder for steps src/shared/steps/../step_file.js
+   * @param {string} path - Path to test
+   * @returns {boolean}
+   */
+  sharedStepsDir: v => v.includes( `${sep}shared${sep}steps${sep}` ),
+  /**
+   * Matches the shared folder for evaluators src/shared/evaluators/../evaluator_file.js
+   * @param {string} path - Path to test
+   * @returns {boolean}
+   */
+  sharedEvaluatorsDir: v => v.includes( `${sep}shared${sep}evaluators${sep}` )
+};

package/src/worker/loader_tools.spec.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, sep } from 'node:path';
 import { importComponents } from './loader_tools.js';
 
 describe( '.importComponents', () => {
@@ -21,7 +21,7 @@ describe( '.importComponents', () => {
     ].join( '\n' ) );
 
     const collected = [];
-    for await ( const m of importComponents( root, [ 'meta.module.js' ] ) ) {
+    for await ( const m of importComponents( root, [ v => v.endsWith( 'meta.module.js' ) ] ) ) {
       collected.push( m );
     }
 
@@ -46,7 +46,7 @@ describe( '.importComponents', () => {
     ].join( '\n' ) );
 
     const collected = [];
-    for await ( const m of importComponents( root, [ 'meta.module.js' ] ) ) {
+    for await ( const m of importComponents( root, [ v => v.endsWith( 'meta.module.js' ) ] ) ) {
       collected.push( m );
     }
 
@@ -77,7 +77,7 @@ describe( '.importComponents', () => {
     writeFileSync( vendorFile, fileContents );
 
     const collected = [];
-    for await ( const m of importComponents( root, [ 'meta.module.js' ] ) ) {
+    for await ( const m of importComponents( root, [ v => v.endsWith( 'meta.module.js' ) ] ) ) {
       collected.push( m );
     }
 
@@ -87,82 +87,31 @@ describe( '.importComponents', () => {
     rmSync( root, { recursive: true, force: true } );
   } );
 
-  it( 'collects all .js files from shared/steps/ directory with isShared flag', async () => {
-    const root = join( process.cwd(), 'sdk/core/temp_test_modules', `meta-${Date.now()}-shared` );
-    const sharedStepsDir = join( root, 'shared', 'steps' );
-    const workflowDir = join( root, 'workflows', 'example' );
-    mkdirSync( sharedStepsDir, { recursive: true } );
-    mkdirSync( workflowDir, { recursive: true } );
-
-    const sharedToolsFile = join( sharedStepsDir, 'tools.js' );
-    const sharedUtilsFile = join( sharedStepsDir, 'utils.js' );
-    const workflowStepsFile = join( workflowDir, 'steps.js' );
-
-    const sharedFileContents = [
-      'import { METADATA_ACCESS_SYMBOL } from "#consts";',
-      'export const SharedStep = () => {};',
-      'SharedStep[METADATA_ACCESS_SYMBOL] = { kind: "step", name: "sharedStep" };'
-    ].join( '\n' );
-    const workflowFileContents = [
-      'import { METADATA_ACCESS_SYMBOL } from "#consts";',
-      'export const LocalStep = () => {};',
-      'LocalStep[METADATA_ACCESS_SYMBOL] = { kind: "step", name: "localStep" };'
-    ].join( '\n' );
-    writeFileSync( sharedToolsFile, sharedFileContents );
-    writeFileSync( sharedUtilsFile, sharedFileContents );
-    writeFileSync( workflowStepsFile, workflowFileContents );
-
-    const collected = [];
-    for await ( const m of importComponents( root, [ 'steps.js' ] ) ) {
-      collected.push( m );
-    }
-
-    expect( collected.length ).toBe( 3 );
-
-    const sharedComponents = collected.filter( m => m.isShared === true );
-    const localComponents = collected.filter( m => !m.isShared );
-
-    expect( sharedComponents.length ).toBe( 2 );
-    expect( localComponents.length ).toBe( 1 );
-
-    expect( sharedComponents.map( m => m.path ).sort() ).toEqual( [ sharedToolsFile, sharedUtilsFile ].sort() );
-    expect( localComponents[0].path ).toBe( workflowStepsFile );
-
-    rmSync( root, { recursive: true, force: true } );
-  } );
-
-  it( 'does not collect shared/steps/ files when searching for workflow.js', async () => {
-    const root = join( process.cwd(), 'sdk/core/temp_test_modules', `meta-${Date.now()}-workflow-exclude` );
-    const sharedStepsDir = join( root, 'shared', 'steps' );
-    const workflowDir = join( root, 'workflows', 'example' );
-    mkdirSync( sharedStepsDir, { recursive: true } );
-    mkdirSync( workflowDir, { recursive: true } );
-
-    const sharedToolsFile = join( sharedStepsDir, 'tools.js' );
-    const workflowFile = join( workflowDir, 'workflow.js' );
+  it( 'supports partial matching by folder name', async () => {
+    const root = join( process.cwd(), 'sdk/core/temp_test_modules', `meta-${Date.now()}-foldermatch` );
+    const okDir = join( root, 'features', 'ok' );
+    const otherDir = join( root, 'features', 'other' );
+    mkdirSync( okDir, { recursive: true } );
+    mkdirSync( otherDir, { recursive: true } );
 
-    const sharedFileContents = [
-      'import { METADATA_ACCESS_SYMBOL } from "#consts";',
-      'export const SharedStep = () => {};',
-      'SharedStep[METADATA_ACCESS_SYMBOL] = { kind: "step", name: "sharedStep" };'
-    ].join( '\n' );
-    const workflowFileContents = [
+    const okFile = join( okDir, 'alpha.js' );
+    const otherFile = join( otherDir, 'beta.js' );
+    const src = [
       'import { METADATA_ACCESS_SYMBOL } from "#consts";',
-      'export default function myWorkflow() {};',
-      'myWorkflow[METADATA_ACCESS_SYMBOL] = { kind: "workflow", name: "myWorkflow" };'
+      'export const X = () => {};',
+      'X[METADATA_ACCESS_SYMBOL] = { kind: "step", name: "x" };'
     ].join( '\n' );
-    writeFileSync( sharedToolsFile, sharedFileContents );
-    writeFileSync( workflowFile, workflowFileContents );
+    writeFileSync( okFile, src );
+    writeFileSync( otherFile, src );
 
+    // Match any JS under a folder named "ok"
+    const matcher = v => v.includes( `${join( 'features', 'ok' )}${sep}` );
     const collected = [];
-    for await ( const m of importComponents( root, [ 'workflow.js' ] ) ) {
+    for await ( const m of importComponents( root, [ matcher ] ) ) {
       collected.push( m );
     }
-
     expect( collected.length ).toBe( 1 );
-    expect( collected[0].path ).toBe( workflowFile );
-    expect( collected[0].metadata.kind ).toBe( 'workflow' );
-    expect( collected[0].isShared ).toBeUndefined();
+    expect( collected[0].path ).toBe( okFile );
 
     rmSync( root, { recursive: true, force: true } );
   } );