feat(cli): display operation logs in real-time during mass-operation run

Author: Plopix

components/cli/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file.
 
+## [5.21.0]
+
+- display operation logs in real-time during `mass-operation run`, with color-coded status and a final drain to ensure all logs are shown
+
 ## [5.20.0]
 
 - bump the schema lib to 6.9.0

components/cli/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Run Commands
+
+```bash
+make run ARGS="<command>"          # Run CLI locally (e.g. ARGS="whoami")
+make staging-run ARGS="<command>"  # Run against staging environment
+make build                         # Build single-platform binary
+make build-all                     # Build all platform binaries
+make codeclean                     # Format with prettier
+```
+
+The runtime is **Bun** (>=1.3). No test framework is configured.
+
+## Architecture
+
+This is the **Crystallize CLI** (`@crystallize/cli`), a Bun-compiled TypeScript CLI using React (Ink) for terminal UI.
+
+### Key Patterns
+
+- **CQRS**: CommandBus (mutations) and QueryBus (reads) via `missive.js`. Handlers are registered in `src/core/di.ts`.
+- **Dependency Injection**: Awilix container configured in `src/core/di.ts` — all services are singletons. Command factories receive their dependencies from the container.
+- **Commander.js**: CLI commands are created as factory functions returning `Command` instances, organized by namespace (root, boilerplate, mass-operation, tenant, token, image, file).
+- **Interactive UI**: React components via Ink with Jotai atoms for state. Most commands support `--no-interactive` for CI/CD.
+
+### Source Layout
+
+- `src/index.ts` — Entry point
+- `src/command/` — CLI command definitions (each exports a factory function)
+- `src/domain/use-cases/` — Business logic handlers (CQRS)
+- `src/domain/contracts/` — Interfaces (logger, fly-system, bus, models)
+- `src/core/di.ts` — DI container wiring (command registration, handler setup)
+- `src/core/` — Infrastructure (logger, file system abstraction, credentials, runner)
+- `src/ui/components/` — Reusable Ink/React terminal components
+- `src/ui/journeys/` — Multi-step interactive flows
+
+### Adding a New Command
+
+1. Create a factory in `src/command/<group>/` returning a `Command`
+2. Define any use-case handlers in `src/domain/use-cases/`
+3. Register in `src/core/di.ts` under the appropriate command group
+
+### File System & Process Execution
+
+File I/O uses a `FlySystem` abstraction (`src/domain/contracts/fly-system.ts`, implemented via Bun APIs). Subprocesses use `Bun.spawn` wrapped in `src/core/create-runner.ts`.
+
+### Credentials
+
+Resolved in priority order: env vars (`CRYSTALLIZE_ACCESS_TOKEN_ID`/`SECRET`) → CLI flags (`--token_id`/`--token_secret`) → stored file (`~/.crystallize/credentials.json`).
+
+## Code Style
+
+- Prettier: 4-space indent, single quotes, trailing commas, semicolons, 120 char width
+- Commit messages: conventional commits (feat, fix, chore, refactor, etc.)
+- TypeScript strict mode with `verbatimModuleSyntax`

components/cli/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crystallize/cli",
-    "version": "5.20.0",
+    "version": "5.21.0",
     "description": "Crystallize CLI",
     "module": "src/index.ts",
     "repository": "https://github.com/CrystallizeAPI/crystallize-cli",

components/cli/src/command/mass-operation/run.tsx

@@ -14,6 +14,14 @@ export type MassOperationBulkTaskResponse = {
     bulkTask: MassOperationBulkTaskError | MassOperationBulkTaskSuccess;
 };
 
+type OperationLogNode = { id: string; input: string; output: string; message: string; status: string; statusCode: number };
+type OperationLogsResponse = {
+    operationLogs: {
+        pageInfo: { endCursor: string; hasNextPage: boolean };
+        edges: { node: OperationLogNode }[];
+    };
+};
+
 type Deps = {
     logger: Logger;
     commandBus: CommandBus;
@@ -90,20 +98,75 @@ export const createRunMassOperationCommand = ({
                 accessTokenSecret: credentials.ACCESS_TOKEN_SECRET,
             });
 
+            const fetchAndDisplayLogs = async (
+                taskId: string,
+                cursor: string | null,
+            ): Promise<{ cursor: string | null; hasNextPage: boolean }> => {
+                const res = await crystallizeClient.nextPimApi<OperationLogsResponse>(getOperationLogs, {
+                    operationId: taskId,
+                    after: cursor || '',
+                    first: 100,
+                });
+                const { operationLogs } = res;
+                if (!operationLogs?.edges) {
+                    return { cursor, hasNextPage: false };
+                }
+                for (const { node } of operationLogs.edges) {
+                    const colorFn =
+                        node.statusCode >= 200 && node.statusCode < 300
+                            ? pc.green
+                            : node.statusCode >= 400
+                                ? pc.red
+                                : pc.yellow;
+                    logger.info(`${colorFn(`[${node.statusCode}]`)} ${node.status} - Operation ${node.id}: ${node.message}`);
+                    if (node.input) {
+                        logger.debug(`  Input: ${JSON.stringify(node.input)}`);
+                    }
+                    if (node.output) {
+                        logger.debug(`  Output: ${JSON.stringify(node.output)}`);
+                    }
+                }
+                return {
+                    cursor: operationLogs.pageInfo.endCursor || cursor,
+                    hasNextPage: operationLogs.pageInfo.hasNextPage,
+                };
+            };
+
             logger.info(`Now, Waiting for task ${pc.yellow(startedTask.id)} to complete...`);
+            let logCursor: string | null = null;
+
             while (startedTask.status !== 'complete') {
-                logger.info(`Task status: ${pc.yellow(startedTask.status)}`);
                 await new Promise((resolve) => setTimeout(resolve, 1000));
-                const res: MassOperationBulkTaskResponse =
-                    await crystallizeClient.nextPimApi<MassOperationBulkTaskResponse>(getMassOperationBulkTask, {
-                        id: startedTask.id,
-                    });
-                const { bulkTask } = res;
+                const results: [MassOperationBulkTaskResponse, { cursor: string | null; hasNextPage: boolean }] =
+                    await Promise.all([
+                        crystallizeClient.nextPimApi<MassOperationBulkTaskResponse>(getMassOperationBulkTask, {
+                            id: startedTask.id,
+                        }),
+                        fetchAndDisplayLogs(startedTask.id, logCursor),
+                    ]);
+                const [taskRes, logResult] = results;
+                logCursor = logResult.cursor;
+                // Drain all available log pages before continuing
+                while (logResult.hasNextPage) {
+                    const next = await fetchAndDisplayLogs(startedTask.id, logCursor);
+                    logCursor = next.cursor;
+                    logResult.hasNextPage = next.hasNextPage;
+                }
+                const { bulkTask } = taskRes;
                 if ('error' in bulkTask) {
                     throw new Error(bulkTask.error);
                 }
                 startedTask = bulkTask;
             }
+
+            // Drain remaining logs
+            let hasMoreLogs = true;
+            while (hasMoreLogs) {
+                const logResult = await fetchAndDisplayLogs(startedTask.id, logCursor);
+                logCursor = logResult.cursor;
+                hasMoreLogs = logResult.hasNextPage;
+            }
+
             logger.success(`Task completed successfully. Task ID: ${pc.yellow(startedTask.id)}`);
         } catch (error) {
             if (error instanceof ZodError) {
@@ -131,3 +194,13 @@ query GET($id:ID!) {
     }
   }
 }`;
+
+const getOperationLogs = `#graphql
+query GET_OPERATION_LOGS($operationId: ID!, $after: String, $first: Int) {
+  operationLogs(after: $after, first: $first, filter: { operationId: $operationId }) {
+    ... on OperationLogConnection {
+      pageInfo { endCursor hasNextPage }
+      edges { node { id input output message status statusCode } }
+    }
+  }
+}`;

components/cli/src/core/create-crystallize-client-builder.ts

@@ -1,30 +1,51 @@
 import { createClient, type ClientConfiguration, type CreateClientOptions } from '@crystallize/js-api-client';
 import type { AsyncCreateClient } from '../domain/contracts/credential-retriever';
+import type { Logger } from '../domain/contracts/logger';
 
 type Deps = {
     crystallizeEnvironment: 'staging' | 'production';
+    logLevels: ('info' | 'debug')[]
+    logger: Logger;
 };
 export const createCrystallizeClientBuilder =
-    ({ crystallizeEnvironment }: Deps): AsyncCreateClient =>
-    async (configuration: ClientConfiguration, options?: CreateClientOptions) => {
-        if (configuration.tenantIdentifier.length > 0 && (configuration.tenantId || '').length === 0) {
-            const tempClient = createClient({
-                ...configuration,
-                origin: crystallizeEnvironment === 'staging' ? '-dev.crystallize.digital' : '.crystallize.com',
-            });
-            const tenantInfo = await tempClient.nextPimApi(
-                `query { tenant(identifier:"${configuration.tenantIdentifier}") { ... on Tenant { id } } }`,
-            );
-            if (!tenantInfo.tenant.id) {
-                throw new Error(`Tenant Id for identifier ${configuration.tenantIdentifier} not found`);
+    ({ crystallizeEnvironment, logLevels, logger }: Deps): AsyncCreateClient =>
+        async (configuration: ClientConfiguration, options?: CreateClientOptions) => {
+
+            if (logLevels.includes('debug')) {
+                options = {
+                    ...options,
+                    profiling: {
+                        onRequestResolved({ resolutionTimeMs, serverTimeMs }, query, variables) {
+                            logger.debug(`Query: ${query}`);
+                            logger.debug(`Variables: ${JSON.stringify(variables)}`);
+                            logger.debug(`Resolution time: ${resolutionTimeMs}ms, Server time: ${serverTimeMs}ms`);
+                        }
+                    }
+                }
             }
-            configuration.tenantId = tenantInfo.tenant.id;
-        }
-        return createClient(
-            {
-                ...configuration,
-                origin: crystallizeEnvironment === 'staging' ? '-dev.crystallize.digital' : '.crystallize.com',
-            },
-            options,
-        );
-    };
+
+            if (configuration.tenantIdentifier.length > 0 && (configuration.tenantId || '').length === 0) {
+                const tempClient = createClient({
+                    ...configuration,
+                    origin: crystallizeEnvironment === 'staging' ? '-dev.crystallize.digital' : '.crystallize.com',
+                });
+                const tenantInfo = await tempClient.nextPimApi<{
+                    tenant: {
+                        id: string;
+                    };
+                }>(
+                    `query { tenant(identifier:"${configuration.tenantIdentifier}") { ... on Tenant { id } } }`,
+                );
+                if (!tenantInfo.tenant.id) {
+                    throw new Error(`Tenant Id for identifier ${configuration.tenantIdentifier} not found`);
+                }
+                configuration.tenantId = tenantInfo.tenant.id;
+            }
+            return createClient(
+                {
+                    ...configuration,
+                    origin: crystallizeEnvironment === 'staging' ? '-dev.crystallize.digital' : '.crystallize.com',
+                },
+                options,
+            );
+        };

components/cli/src/domain/core/fetch-available-tenant-identifier.ts

@@ -7,15 +7,19 @@ type Deps = {
 
 export const createFetchAvailableTenantIdentifier =
     ({ createCrystallizeClient }: Deps) =>
-    async (credentials: PimCredentials, identifier: string) => {
-        const apiClient = await createCrystallizeClient({
-            tenantIdentifier: '',
-            sessionId: credentials.sessionId,
-            accessTokenId: credentials.ACCESS_TOKEN_ID,
-            accessTokenSecret: credentials.ACCESS_TOKEN_SECRET,
-        });
-        const result = await apiClient.pimApi(
-            `query { tenant { suggestIdentifier ( desired: "${identifier}" ) { suggestion } } }`,
-        );
-        return result.tenant?.suggestIdentifier?.suggestion || identifier;
-    };
+        async (credentials: PimCredentials, identifier: string) => {
+            const apiClient = await createCrystallizeClient({
+                tenantIdentifier: '',
+                sessionId: credentials.sessionId,
+                accessTokenId: credentials.ACCESS_TOKEN_ID,
+                accessTokenSecret: credentials.ACCESS_TOKEN_SECRET,
+            });
+            const result = await apiClient.pimApi<{
+                tenant: {
+                    suggestIdentifier: {
+                        suggestion: string;
+                    };
+                };
+            }>(`query { tenant { suggestIdentifier ( desired: "${identifier}" ) { suggestion } } }`);
+            return result.tenant?.suggestIdentifier?.suggestion || identifier;
+        };