@outputai/core 0.1.0

package/src/tracing/processors/s3/index.js

@@ -0,0 +1,114 @@
+import { upload } from './s3_client.js';
+import { getRedisClient } from './redis_client.js';
+import buildTraceTree from '../../tools/build_trace_tree.js';
+import { EOL } from 'node:os';
+import { loadEnv, getVars } from './configs.js';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'S3 Processor' );
+
+const createRedisKey = ( { workflowId, workflowName } ) => `traces/${workflowName}/${workflowId}`;
+
+/**
+ * Add new entry to list of entries
+ * @param {object} entry
+ * @param {string} key
+ */
+const addEntry = async ( entry, key ) => {
+  const client = await getRedisClient();
+  await client.multi()
+    .zAdd( key, [ { score: entry.timestamp, value: JSON.stringify( entry ) } ], { NX: true } )
+    .expire( key, getVars().redisIncompleteWorkflowsTTL )
+    .exec();
+};
+
+/**
+ * Returns entries from cache, parsed to object
+ * @param {string} key
+ * @returns {object[]}
+ */
+const getEntries = async key => {
+  const client = await getRedisClient();
+  const zList = await client.zRange( key, 0, -1 );
+  return zList.map( v => JSON.parse( v ) );
+};
+
+/**
+ * Removes the entries from cache
+ * @param {string} key
+ */
+const bustEntries = async key => {
+  const client = await getRedisClient();
+  await client.del( key );
+};
+
+/**
+ * Return the S3 key for the trace file
+ * @param {object} args
+ * @param {number} args.startTime
+ * @param {string} args.workflowId
+ * @param {string} args.workflowName
+ * @returns
+ */
+const getS3Key = ( { startTime, workflowId, workflowName } ) => {
+  const isoDate = new Date( startTime ).toISOString();
+  const [ year, month, day ] = isoDate.split( /\D/, 3 );
+  const timeStamp = isoDate.replace( /[:T.]/g, '-' );
+  return `${workflowName}/${year}/${month}/${day}/${timeStamp}_${workflowId}.json`;
+};
+
+/**
+ * Init this processor
+ */
+export const init = async () => {
+  loadEnv();
+  await getRedisClient();
+};
+
+/**
+ * Execute this processor: send a complete trace tree file to S3 when the workflow finishes
+ *
+ * @param {object} args
+ * @param {object} entry - Trace event phase
+ * @param {object} executionContext - Execution info: workflowId, workflowName, startTime
+ */
+export const exec = async ( { entry, executionContext } ) => {
+  const { workflowName, workflowId, startTime } = executionContext;
+  const cacheKey = createRedisKey( { workflowId, workflowName } );
+
+  await addEntry( entry, cacheKey );
+
+  const isRootWorkflowEnd = entry.id === workflowId && entry.phase !== 'start';
+  if ( !isRootWorkflowEnd ) {
+    return;
+  }
+
+  // Wait for straggler entries from other workers to land in Redis before uploading
+  const delayMs = getVars().traceUploadDelayMs;
+  if ( delayMs > 0 ) {
+    await new Promise( resolve => setTimeout( resolve, delayMs ) );
+  }
+
+  const content = buildTraceTree( await getEntries( cacheKey ) );
+  // if the trace tree is incomplete it will return null, in this case we can safely discard
+  if ( !content ) {
+    log.warn( 'Incomplete trace file discarded', { workflowId, error: 'incomplete_trace_file' } );
+    return;
+  }
+  await upload( {
+    key: getS3Key( { workflowId, workflowName, startTime } ),
+    content: JSON.stringify( content, undefined, 2 ) + EOL
+  } );
+  await bustEntries( cacheKey );
+};
+
+/**
+ * Returns where the trace is saved
+ * @param {object} executionContext
+ * @param {string} executionContext.startTime - The start time of the workflow
+ * @param {string} executionContext.workflowId - The id of the workflow execution
+ * @param {string} executionContext.workflowName - The name of the workflow
+ * @returns {string} The S3 url of the trace file
+ */
+export const getDestination = ( { startTime, workflowId, workflowName } ) =>
+  `https://${getVars().remoteS3Bucket}.s3.amazonaws.com/${getS3Key( { workflowId, workflowName, startTime } )}`;

package/src/tracing/processors/s3/index.spec.js

@@ -0,0 +1,153 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const loadEnvMock = vi.fn();
+const getVarsMock = vi.fn( () => ( {
+  remoteS3Bucket: 'bkt',
+  redisIncompleteWorkflowsTTL: 3600
+} ) );
+vi.mock( './configs.js', () => ( { loadEnv: loadEnvMock, getVars: getVarsMock } ) );
+
+const redisMulti = {
+  zAdd: vi.fn().mockReturnThis(),
+  expire: vi.fn().mockReturnThis(),
+  exec: vi.fn()
+};
+const zRangeMock = vi.fn();
+const delMock = vi.fn().mockResolvedValue( undefined );
+const getRedisClientMock = vi.fn( async () => ( {
+  multi: () => redisMulti,
+  zRange: zRangeMock,
+  del: delMock
+} ) );
+vi.mock( './redis_client.js', () => ( { getRedisClient: getRedisClientMock } ) );
+
+const uploadMock = vi.fn();
+vi.mock( './s3_client.js', () => ( { upload: uploadMock } ) );
+
+const buildTraceTreeMock = vi.fn( entries => ( { count: entries.length } ) );
+vi.mock( '../../tools/build_trace_tree.js', () => ( { default: buildTraceTreeMock } ) );
+
+describe( 'tracing/processors/s3', () => {
+  beforeEach( () => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+    getVarsMock.mockReturnValue( { remoteS3Bucket: 'bkt', redisIncompleteWorkflowsTTL: 3600, traceUploadDelayMs: 10_000 } );
+  } );
+
+  afterEach( () => {
+    vi.useRealTimers();
+  } );
+
+  it( 'init(): loads config and ensures redis client is created', async () => {
+    const { init } = await import( './index.js' );
+    await init();
+    expect( loadEnvMock ).toHaveBeenCalledTimes( 1 );
+    expect( getRedisClientMock ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'exec(): accumulates via redis, uploads only on root workflow end', async () => {
+    const { exec } = await import( './index.js' );
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+
+    redisMulti.exec.mockResolvedValue( [] );
+
+    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', phase: 'start', details: {}, timestamp: startTime };
+    const activityStart = { id: 'act-1', name: 'DoSomething', kind: 'step', parentId: 'id1', phase: 'start', details: {}, timestamp: startTime + 1 };
+    const workflowEnd = { id: 'id1', phase: 'end', details: { ok: true }, timestamp: startTime + 2 };
+    zRangeMock.mockResolvedValue( [
+      JSON.stringify( workflowStart ),
+      JSON.stringify( activityStart ),
+      JSON.stringify( workflowEnd )
+    ] );
+
+    await exec( { ...ctx, entry: workflowStart } );
+    await exec( { ...ctx, entry: activityStart } );
+    // Root end: id matches workflowId and not start — triggers the 10s delay before upload
+    const endPromise = exec( { ...ctx, entry: workflowEnd } );
+    await vi.advanceTimersByTimeAsync( 10_000 );
+    await endPromise;
+
+    expect( redisMulti.zAdd ).toHaveBeenCalledTimes( 3 );
+    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 1 );
+    expect( zRangeMock ).toHaveBeenCalledTimes( 1 );
+    expect( uploadMock ).toHaveBeenCalledTimes( 1 );
+    const { key, content } = uploadMock.mock.calls[0][0];
+    expect( key ).toMatch( /^WF\/2020\/01\/02\// );
+    expect( JSON.parse( content.trim() ).count ).toBe( 3 );
+    expect( delMock ).toHaveBeenCalledTimes( 1 );
+    expect( delMock ).toHaveBeenCalledWith( 'traces/WF/id1' );
+  } );
+
+  it( 'getDestination(): returns S3 URL using bucket and key from getVars', async () => {
+    getVarsMock.mockReturnValue( { remoteS3Bucket: 'my-bucket', redisIncompleteWorkflowsTTL: 3600, traceUploadDelayMs: 10_000 } );
+    const { getDestination } = await import( './index.js' );
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const url = getDestination( { workflowId: 'id1', workflowName: 'WF', startTime } );
+    expect( getVarsMock ).toHaveBeenCalled();
+    expect( url ).toBe(
+      'https://my-bucket.s3.amazonaws.com/WF/2020/01/02/2020-01-02-03-04-05-678Z_id1.json'
+    );
+  } );
+
+  it( 'exec(): sets expiry on the redis key for each entry', async () => {
+    const { exec } = await import( './index.js' );
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+
+    redisMulti.exec.mockResolvedValue( [] );
+    const workflowStart = {
+      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, phase: 'start', details: {}, timestamp: startTime
+    };
+    zRangeMock.mockResolvedValue( [ JSON.stringify( workflowStart ) ] );
+
+    await exec( { ...ctx, entry: workflowStart } );
+
+    expect( redisMulti.expire ).toHaveBeenCalledTimes( 1 );
+    expect( redisMulti.expire ).toHaveBeenCalledWith( 'traces/WF/id1', 3600 );
+  } );
+
+  it( 'exec(): does not treat a non-root end (e.g. step without parentId) as root workflow end — regression for wrong root detection', async () => {
+    const { exec } = await import( './index.js' );
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+
+    redisMulti.exec.mockResolvedValue( [] );
+    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', phase: 'start', details: {}, timestamp: startTime };
+    const stepEndNoParent = { id: 'step-1', phase: 'end', details: { done: true }, timestamp: startTime + 1 };
+    zRangeMock.mockResolvedValue( [
+      JSON.stringify( workflowStart ),
+      JSON.stringify( stepEndNoParent )
+    ] );
+
+    await exec( { ...ctx, entry: workflowStart } );
+    await exec( { ...ctx, entry: stepEndNoParent } );
+
+    expect( redisMulti.zAdd ).toHaveBeenCalledTimes( 2 );
+    expect( buildTraceTreeMock ).not.toHaveBeenCalled();
+    expect( uploadMock ).not.toHaveBeenCalled();
+    expect( delMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'exec(): when buildTraceTree returns null (incomplete tree), does not upload or bust cache', async () => {
+    const { exec } = await import( './index.js' );
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+
+    redisMulti.exec.mockResolvedValue( [] );
+    const workflowEnd = {
+      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, phase: 'end', details: {}, timestamp: startTime
+    };
+    zRangeMock.mockResolvedValue( [ JSON.stringify( workflowEnd ) ] );
+    buildTraceTreeMock.mockReturnValueOnce( null );
+
+    const endPromise = exec( { ...ctx, entry: workflowEnd } );
+    await vi.advanceTimersByTimeAsync( 10_000 );
+    await endPromise;
+
+    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 1 );
+    expect( uploadMock ).not.toHaveBeenCalled();
+    expect( delMock ).not.toHaveBeenCalled();
+  } );
+} );
+

package/src/tracing/processors/s3/redis_client.js

@@ -0,0 +1,62 @@
+import { createClient } from 'redis';
+import { createChildLogger } from '#logger';
+import { getVars } from './configs.js';
+
+const log = createChildLogger( 'RedisClient' );
+
+const state = {
+  client: null,
+  connectPromise: null
+};
+
+async function connect( url ) {
+  if ( state.client ) {
+    log.warn( 'Closing stale Redis client before reconnecting' );
+    await state.client.quit().catch( quitErr => {
+      log.warn( 'Failed to quit stale Redis client', { error: quitErr.message } );
+    } );
+    state.client = null;
+  }
+
+  const client = createClient( { url, socket: { keepAlive: 15000 } } );
+  try {
+    await client.connect();
+    return state.client = client;
+  } catch ( err ) {
+    await client.quit().catch( () => {} );
+    throw new Error( `Failed to connect to Redis: ${err.message} (${err.code || 'UNKNOWN'})`, { cause: err } );
+  }
+}
+
+/**
+ * Return a connected Redis instance with automatic reconnection.
+ *
+ * Performs health check on cached client via ping(). If healthy, returns cached
+ * instance. Otherwise, closes stale client before creating new connection.
+ * Concurrent calls during connection will receive the same pending promise.
+ *
+ * @returns {Promise<redis.RedisClientType>} Connected Redis client
+ * @throws {Error} If connection fails (wrapped with context)
+ */
+export async function getRedisClient() {
+  const url = getVars().redisUrl;
+
+  const pingResult = await state.client?.ping().catch( err => {
+    log.error( 'Redis ping failed', { error: err.message, code: err.code } );
+    return null;
+  } );
+
+  if ( pingResult === 'PONG' ) {
+    return state.client;
+  }
+
+  if ( state.connectPromise ) {
+    return state.connectPromise;
+  }
+
+  state.connectPromise = connect( url ).finally( () => {
+    state.connectPromise = null;
+  } );
+
+  return state.connectPromise;
+}

package/src/tracing/processors/s3/redis_client.spec.js

@@ -0,0 +1,185 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock( '#utils', () => ( {
+  throws: e => {
+    throw e;
+  }
+} ) );
+
+const logCalls = { warn: [], error: [] };
+vi.mock( '#logger', () => ( {
+  createChildLogger: () => ( {
+    warn: ( ...args ) => logCalls.warn.push( args ),
+    error: ( ...args ) => logCalls.error.push( args )
+  } )
+} ) );
+
+const getVarsMock = vi.fn();
+vi.mock( './configs.js', () => ( { getVars: () => getVarsMock() } ) );
+
+const createClientImpl = vi.fn();
+vi.mock( 'redis', () => ( { createClient: opts => createClientImpl( opts ) } ) );
+
+async function loadModule() {
+  vi.resetModules();
+  return import( './redis_client.js' );
+}
+
+describe( 'tracing/processors/s3/redis_client', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    getVarsMock.mockReturnValue( {} );
+    logCalls.warn = [];
+    logCalls.error = [];
+  } );
+
+  afterEach( () => {
+    vi.useRealTimers();
+  } );
+
+  it( 'throws when config redisUrl is missing', async () => {
+    getVarsMock.mockReturnValue( {} );
+    const { getRedisClient } = await loadModule();
+    await expect( getRedisClient() ).rejects.toThrow();
+  } );
+
+  it( 'creates client with url, connects once, then reuses cached when ping is PONG', async () => {
+    getVarsMock.mockReturnValue( { redisUrl: 'redis://localhost:6379' } );
+
+    const pingMock = vi.fn().mockResolvedValue( 'PONG' );
+    const connectMock = vi.fn().mockResolvedValue();
+    const created = [];
+    createClientImpl.mockImplementation( opts => {
+      created.push( opts );
+      return { connect: connectMock, ping: pingMock };
+    } );
+
+    const { getRedisClient } = await loadModule();
+
+    const c1 = await getRedisClient();
+    const c2 = await getRedisClient();
+
+    expect( created ).toHaveLength( 1 );
+    expect( connectMock ).toHaveBeenCalledTimes( 1 );
+    expect( pingMock ).toHaveBeenCalledTimes( 1 );
+    expect( c1 ).toBe( c2 );
+    expect( created[0] ).toMatchObject( { url: 'redis://localhost:6379', socket: { keepAlive: 15000 } } );
+  } );
+
+  it( 'closes stale client and reconnects when ping fails', async () => {
+    getVarsMock.mockReturnValue( { redisUrl: 'redis://localhost:6379' } );
+
+    const quitMock = vi.fn().mockResolvedValue();
+    const connectMock = vi.fn().mockResolvedValue();
+    const pingMock = vi.fn()
+      .mockResolvedValueOnce( 'PONG' )
+      .mockRejectedValueOnce( new Error( 'Connection lost' ) )
+      .mockResolvedValueOnce( 'PONG' );
+
+    const created = [];
+    createClientImpl.mockImplementation( opts => {
+      created.push( opts );
+      return { connect: connectMock, ping: pingMock, quit: quitMock };
+    } );
+
+    const { getRedisClient } = await loadModule();
+
+    const c1 = await getRedisClient();
+    const c2 = await getRedisClient();
+    expect( c1 ).toBe( c2 );
+    expect( created ).toHaveLength( 1 );
+
+    const c3 = await getRedisClient();
+    expect( quitMock ).toHaveBeenCalledTimes( 1 );
+    expect( created ).toHaveLength( 2 );
+    expect( c3 ).not.toBe( c1 );
+  } );
+
+  it( 'reconnects successfully even when quit() on stale client rejects', async () => {
+    getVarsMock.mockReturnValue( { redisUrl: 'redis://localhost:6379' } );
+
+    const quitMock = vi.fn().mockRejectedValue( new Error( 'Quit failed' ) );
+    const connectMock = vi.fn().mockResolvedValue();
+    const pingMock = vi.fn()
+      .mockResolvedValueOnce( 'PONG' )
+      .mockRejectedValueOnce( new Error( 'Connection lost' ) )
+      .mockResolvedValueOnce( 'PONG' );
+
+    const created = [];
+    createClientImpl.mockImplementation( opts => {
+      created.push( opts );
+      return { connect: connectMock, ping: pingMock, quit: quitMock };
+    } );
+
+    const { getRedisClient } = await loadModule();
+
+    const c1 = await getRedisClient();
+    const c1again = await getRedisClient();
+    expect( c1 ).toBe( c1again );
+    expect( created ).toHaveLength( 1 );
+
+    const c2 = await getRedisClient();
+    expect( quitMock ).toHaveBeenCalledTimes( 1 );
+    expect( created ).toHaveLength( 2 );
+    expect( c2 ).not.toBe( c1 );
+  } );
+
+  it( 'wraps connect() errors with code and cleans up failed client', async () => {
+    getVarsMock.mockReturnValue( { redisUrl: 'redis://localhost:6379' } );
+
+    const connectErr = new Error( 'Connection refused' );
+    connectErr.code = 'ECONNREFUSED';
+    const connectMock = vi.fn().mockRejectedValue( connectErr );
+    const quitMock = vi.fn().mockResolvedValue();
+
+    createClientImpl.mockImplementation( () => ( {
+      connect: connectMock,
+      quit: quitMock
+    } ) );
+
+    const { getRedisClient } = await loadModule();
+
+    try {
+      await getRedisClient();
+      expect.fail( 'Should have thrown' );
+    } catch ( err ) {
+      expect( err.message ).toBe( 'Failed to connect to Redis: Connection refused (ECONNREFUSED)' );
+      expect( err.cause ).toBe( connectErr );
+    }
+
+    expect( quitMock ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'logs ping failures with error level', async () => {
+    getVarsMock.mockReturnValue( { redisUrl: 'redis://localhost:6379' } );
+
+    const pingErr = new Error( 'Connection reset' );
+    pingErr.code = 'ECONNRESET';
+    const pingMock = vi.fn()
+      .mockResolvedValueOnce( 'PONG' )
+      .mockRejectedValueOnce( pingErr )
+      .mockResolvedValueOnce( 'PONG' );
+    const connectMock = vi.fn().mockResolvedValue();
+    const quitMock = vi.fn().mockResolvedValue();
+
+    createClientImpl.mockImplementation( () => ( {
+      connect: connectMock,
+      ping: pingMock,
+      quit: quitMock
+    } ) );
+
+    const { getRedisClient } = await loadModule();
+
+    // First call: state.client is null, creates client (no ping)
+    await getRedisClient();
+    // Second call: pings existing client, returns PONG
+    await getRedisClient();
+    // Third call: pings existing client, fails with pingErr, reconnects
+    await getRedisClient();
+
+    expect( logCalls.error ).toContainEqual( [
+      'Redis ping failed',
+      { error: 'Connection reset', code: 'ECONNRESET' }
+    ] );
+  } );
+} );

package/src/tracing/processors/s3/s3_client.js

@@ -0,0 +1,27 @@
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { getVars } from './configs.js';
+
+const state = { s3Client: null };
+
+/**
+ * Return a S3 Client instance
+ * @returns {S3Client}
+ */
+const getS3Client = () => {
+  if ( state.s3Client ) {
+    return state.s3Client;
+  }
+
+  const { awsRegion: region, awsSecretAccessKey: secretAccessKey, awsAccessKeyId: accessKeyId } = getVars();
+
+  return state.s3Client = new S3Client( { region, credentials: { accessKeyId, secretAccessKey } } );
+};
+
+/**
+ * Upload given file to S3
+ * @param {object} args
+ * @param {string} key - S3 file key
+ * @param {string} content - File content
+ */
+export const upload = ( { key, content } ) =>
+  getS3Client().send( new PutObjectCommand( { Bucket: getVars().remoteS3Bucket, Key: key, Body: content } ) );

package/src/tracing/processors/s3/s3_client.spec.js

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock( '#utils', () => ( {
+  throws: e => {
+    throw e;
+  }
+} ) );
+
+const getVarsMock = vi.fn();
+vi.mock( './configs', () => ( { getVars: () => getVarsMock() } ) );
+
+const sendMock = vi.fn();
+const ctorState = { args: null };
+class S3ClientMock {
+  constructor( args ) {
+    ctorState.args = args;
+  } send = sendMock;
+}
+class PutObjectCommandMock {
+  constructor( input ) {
+    this.input = input;
+  }
+}
+
+vi.mock( '@aws-sdk/client-s3', () => ( {
+  S3Client: S3ClientMock,
+  PutObjectCommand: PutObjectCommandMock
+} ) );
+
+async function loadModule() {
+  vi.resetModules();
+  return import( './s3_client.js' );
+}
+
+describe( 'tracing/processors/s3/s3_client', () => {
+  beforeEach( () => {
+    vi.clearAllMocks();
+    getVarsMock.mockReturnValue( {
+      awsRegion: 'us-east-1',
+      awsAccessKeyId: 'id',
+      awsSecretAccessKey: 'sek',
+      remoteS3Bucket: 'bucket'
+    } );
+  } );
+
+  it( 'creates client once with config and uploads with bucket/key/content', async () => {
+    const { upload } = await loadModule();
+
+    await upload( { key: 'wf/key.json', content: '{"a":1}' } );
+
+    expect( ctorState.args ).toEqual( { region: 'us-east-1', credentials: { secretAccessKey: 'sek', accessKeyId: 'id' } } );
+    expect( sendMock ).toHaveBeenCalledTimes( 1 );
+    const cmd = sendMock.mock.calls[0][0];
+    expect( cmd ).toBeInstanceOf( PutObjectCommandMock );
+    expect( cmd.input ).toEqual( { Bucket: 'bucket', Key: 'wf/key.json', Body: '{"a":1}' } );
+
+    // subsequent upload uses cached client
+    await upload( { key: 'wf/key2.json', content: '{}' } );
+    expect( sendMock ).toHaveBeenCalledTimes( 2 );
+  } );
+} );
+

package/src/tracing/tools/build_trace_tree.js

@@ -0,0 +1,83 @@
+/**
+ * @typedef {object} NodeEntry
+ * @property {string} id
+ * @property {string} kind
+ * @property {string} name
+ * @property {number} startedAt
+ * @property {number} endedAt
+ * @property {object} [input]
+ * @property {object} [output]
+ * @property {object} [error]
+ * @property {NodeTree[]} children
+ */
+/**
+ * Create a node entry for the tree.
+ *
+ * Properties are sorted the way they should be in the final file, as this makes it easier to read.
+ *
+ * @param {string} id - Node id
+ * @returns {NodeEntry} The entry without any values
+ */
+const createEntry = id => ( {
+  id,
+  kind: '',
+  name: '',
+  startedAt: 0,
+  endedAt: null,
+  input: undefined,
+  output: undefined,
+  error: undefined,
+  children: []
+} );
+
+/**
+ * Build a tree of nodes from a list of entries
+ *
+ * Each node will have: id, name, kind, children, input, output or error, startedAt, endedAt.
+ *
+ * Entries with same id will be combined according to their phase (start, end OR error).
+ * - The details of the start phase becomes input, timestamp becomes startedAt;
+ * - The details of the end phase become output, timestamp becomes endedAt;
+ * - The details of the error phase become error, timestamp becomes endedAt;
+ * - Only start phase's kind and name are used;
+ *
+ *
+ * Children are added according to the parentId of each entry.
+ * The result tree has a single root: the only node without parentId, normally the workflow itself.
+ *
+ * @param {object[]} entries - The list of entries
+ * @returns {object}
+ */
+export default entries => {
+  const nodes = new Map();
+  const ensureNode = id => nodes.get( id ) ?? nodes.set( id, createEntry( id ) ).get( id );
+
+  for ( const entry of entries ) {
+    const { kind, id, name, parentId, details, phase, timestamp } = entry;
+    const node = ensureNode( id );
+
+    if ( phase === 'start' ) {
+      Object.assign( node, { input: details, startedAt: timestamp, kind, name } );
+    } else if ( phase === 'end' ) {
+      Object.assign( node, { output: details, endedAt: timestamp } );
+    } else if ( phase === 'error' ) {
+      Object.assign( node, { error: details, endedAt: timestamp } );
+    }
+
+    if ( parentId && phase === 'start' ) {
+      const parent = ensureNode( parentId );
+      parent.children.push( node );
+      parent.children.sort( ( a, b ) => a.startedAt - b.startedAt );
+    }
+  }
+
+  const rootNode = nodes.get( entries.find( e => !e.parentId )?.id );
+  if ( !rootNode ) {
+    return null;
+  }
+  if ( !rootNode.endedAt ) {
+    rootNode.output = '<<Workflow did not finish yet. If this workflows is supposed to have been completed already, \
+this can indicate it timed out or was interrupted.>>';
+  }
+  return rootNode;
+};