feat(cli): add reporter for migrations

maoberlehner · maoberlehner · commit 3170abfe94e4 · 2025-11-24T11:20:22.000+01:00
See: WDX-190
diff --git a/packages/cli/src/commands/logs/list/index.test.ts b/packages/cli/src/commands/logs/list/index.test.ts
@@ -4,15 +4,15 @@ import path from 'node:path';
 // Import the main components module first to ensure proper initialization
 import '../index';
 import { logsCommand } from '../command';
-import { getLogsPath } from '../../../utils/filesystem';
+import { resolveCommandPath } from '../../../utils/filesystem';
 
 vi.mock('node:fs');
 vi.mock('node:fs/promises');
 
 vi.spyOn(console, 'info');
 vi.spyOn(console, 'log');
 
-const LOGS_FILE_DIR = getLogsPath('logs', '12345');
+const LOGS_FILE_DIR = resolveCommandPath('logs', '12345');
 
 const preconditions = {
   hasLogFiles() {
diff --git a/packages/cli/src/commands/logs/list/index.ts b/packages/cli/src/commands/logs/list/index.ts
@@ -1,4 +1,4 @@
-import { getLogsPath } from '../../../utils/filesystem';
+import { resolveCommandPath } from '../../../utils/filesystem';
 import { getUI } from '../../../utils/ui';
 import { logsCommand } from '../command';
 import { FileTransport } from '../../../utils/logger-transport-file';
@@ -9,7 +9,7 @@ logsCommand.command('list')
   .action(async () => {
     const { space, path } = logsCommand.opts();
     const ui = getUI();
-    const logsPath = getLogsPath(directories.log, space, path);
+    const logsPath = resolveCommandPath(directories.log, space, path);
     const logFiles = FileTransport.listLogFiles(logsPath);
 
     if (logFiles.length === 0) {
diff --git a/packages/cli/src/commands/logs/prune/index.test.ts b/packages/cli/src/commands/logs/prune/index.test.ts
@@ -4,15 +4,15 @@ import path from 'node:path';
 // Import the main components module first to ensure proper initialization
 import '../index';
 import { logsCommand } from '../command';
-import { getLogsPath } from '../../../utils/filesystem';
+import { resolveCommandPath } from '../../../utils/filesystem';
 
 vi.mock('node:fs');
 vi.mock('node:fs/promises');
 
 vi.spyOn(console, 'info');
 vi.spyOn(console, 'log');
 
-const LOGS_FILE_DIR = getLogsPath('logs', '12345');
+const LOGS_FILE_DIR = resolveCommandPath('logs', '12345');
 
 const preconditions = {
   hasLogFiles() {
diff --git a/packages/cli/src/commands/logs/prune/index.ts b/packages/cli/src/commands/logs/prune/index.ts
@@ -1,4 +1,4 @@
-import { getLogsPath } from '../../../utils/filesystem';
+import { resolveCommandPath } from '../../../utils/filesystem';
 import { getUI } from '../../../utils/ui';
 import { logsCommand } from '../command';
 import { FileTransport } from '../../../utils/logger-transport-file';
@@ -10,7 +10,7 @@ logsCommand.command('prune')
   .action(async ({ keep }: { keep: number }) => {
     const { space, path } = logsCommand.opts();
     const ui = getUI();
-    const logsPath = getLogsPath(directories.log, space, path);
+    const logsPath = resolveCommandPath(directories.log, space, path);
     const deletedFilesCount = FileTransport.pruneLogFiles(logsPath, keep);
 
     ui.info(`Deleted ${deletedFilesCount} log file${deletedFilesCount === 1 ? '' : 's'}`);
diff --git a/packages/cli/src/commands/migrations/run/index.test.ts b/packages/cli/src/commands/migrations/run/index.test.ts
@@ -147,6 +147,37 @@ describe('migrations run command', () => {
       }),
     );
     expect(fetchStory).toHaveBeenCalledWith('12345', '517473243');
+    // Report
+    const reportFile = Object.entries(vol.toJSON())
+      .find(([filename]) => filename.includes('reports/12345/storyblok-migrations-run-'))?.[1];
+    expect(JSON.parse(reportFile || '{}')).toEqual({
+      status: 'SUCCESS',
+      meta: {
+        runId: expect.any(String),
+        command: 'storyblok migrations run',
+        cliVersion: expect.any(String),
+        startedAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/),
+        endedAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/),
+        durationMs: expect.any(Number),
+        logPath: expect.any(String),
+        config: {
+          space: '12345',
+        },
+      },
+      summary: {
+        migrationResults: {
+          failed: 0,
+          skipped: 0,
+          succeeded: 1,
+          total: 1,
+        },
+        updateResults: {
+          failed: 0,
+          succeeded: 1,
+          total: 1,
+        },
+      },
+    });
     // Logging
     const logFile = getLogFileContents();
     expect(logFile).toContain('Migration finished');
@@ -167,6 +198,26 @@ describe('migrations run command', () => {
     await migrationsCommand.parseAsync(['node', 'test', 'run', '--space', '12345']);
 
     expect(updateStory).not.toHaveBeenCalled();
+    // Report
+    const reportFile = Object.entries(vol.toJSON())
+      .find(([filename]) => filename.includes('reports/12345/storyblok-migrations-run-'))?.[1];
+    expect(JSON.parse(reportFile || '{}')).toEqual({
+      status: 'FAILURE',
+      meta: expect.any(Object),
+      summary: {
+        migrationResults: {
+          failed: 1,
+          skipped: 0,
+          succeeded: 0,
+          total: 1,
+        },
+        updateResults: {
+          failed: 0,
+          succeeded: 0,
+          total: 0,
+        },
+      },
+    });
     // Logging
     const logFile = getLogFileContents();
     expect(logFile).toContain('Couldn\'t load migration function');
diff --git a/packages/cli/src/commands/migrations/run/index.ts b/packages/cli/src/commands/migrations/run/index.ts
@@ -1,6 +1,7 @@
 import { getProgram } from '../../../program';
 import { getUI } from '../../../utils/ui';
 import { getLogger } from '../../../utils/logger';
+import { getReporter } from '../../../utils/reporter';
 import { colorPalette, commands } from '../../../constants';
 import { CommandError, handleError, requireAuthentication } from '../../../utils';
 import { session } from '../../../session';
@@ -24,6 +25,7 @@ migrationsCommand.command('run [componentName]')
     const program = getProgram();
     const ui = getUI();
     const logger = getLogger();
+    const reporter = getReporter();
 
     ui.title(`${commands.MIGRATIONS}`, colorPalette.MIGRATIONS, componentName ? `Running migrations for component ${componentName}...` : 'Running migrations...');
     logger.info('Migration started');
@@ -150,22 +152,27 @@ migrationsCommand.command('run [componentName]')
       const updateSummary = updateStream.getSummary();
       ui.info(updateSummary);
 
-      const migrationResults = migrationStream.getResults();
-      const updateResults = updateStream.getResults();
+      const migrationStreamResults = migrationStream.getResults();
+      const migrationResults = {
+        total: migrationStreamResults.totalProcessed,
+        succeeded: migrationStreamResults.successful.length,
+        skipped: migrationStreamResults.skipped.length,
+        failed: migrationStreamResults.failed.length,
+      };
+      const updateStreamResults = updateStream.getResults();
+      const updateResults = {
+        total: updateStreamResults.totalProcessed,
+        succeeded: updateStreamResults.successful.length,
+        failed: updateStreamResults.failed.length,
+      };
 
       logger.info('Migration finished', {
-        migrationResults: {
-          total: migrationResults.totalProcessed,
-          succeeded: migrationResults.successful.length,
-          skipped: migrationResults.skipped.length,
-          failed: migrationResults.failed.length,
-        },
-        updateResults: {
-          total: updateResults.totalProcessed,
-          succeeded: updateResults.successful.length,
-          failed: updateResults.failed.length,
-        },
+        migrationResults,
+        updateResults,
       });
+      reporter.addSummary('migrationResults', migrationResults);
+      reporter.addSummary('updateResults', updateResults);
+      reporter.finalize();
     }
     catch (error) {
       handleError(error as Error, verbose);
diff --git a/packages/cli/src/constants.ts b/packages/cli/src/constants.ts
@@ -88,4 +88,5 @@ export interface SpaceOptions {
 
 export const directories = {
   log: 'logs',
+  report: 'reports',
 } as const;
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
@@ -14,7 +14,6 @@ import './commands/types';
 import './commands/datasources';
 import './commands/create';
 import './commands/logs';
-import pkg from '../package.json';
 
 import { colorPalette } from './constants';
 
@@ -27,10 +26,6 @@ konsola.br();
 konsola.br();
 konsola.title(` Storyblok CLI `, colorPalette.PRIMARY);
 
-program.option('--verbose', 'Enable verbose output');
-program.version(pkg.version, '-v, --vers', 'Output the current version');
-program.helpOption('-h, --help', 'Display help for command');
-
 program.on('command:*', () => {
   console.error(`Invalid command: ${program.args.join(' ')}`);
   konsola.br();
diff --git a/packages/cli/src/program.ts b/packages/cli/src/program.ts
@@ -6,8 +6,9 @@ import { __dirname, handleError } from './utils';
 import type { LogTransport } from './utils/logger';
 import { getLogger } from './utils/logger';
 import { getUI } from './utils/ui';
+import { getReporter } from './utils/reporter';
 import { FileTransport } from './utils/logger-transport-file';
-import { getLogsPath } from './utils/filesystem';
+import { resolveCommandPath } from './utils/filesystem';
 import { directories } from './constants';
 
 let packageJson: NormalizedPackageJson;
@@ -44,7 +45,9 @@ export function getProgram(): Command {
     programInstance
       .name(packageJson.name)
       .description(packageJson.description || '')
-      .version(packageJson.version)
+      .version(packageJson.version, '-v, --vers', 'Output the current version')
+      .helpOption('-h, --help', 'Display help for command')
+      .option('--verbose', 'Enable verbose output')
       .hook('preAction', (_, actionCmd) => {
         const options = actionCmd.optsWithGlobals();
         const commandPieces: string[] = [];
@@ -55,7 +58,7 @@ export function getProgram(): Command {
 
         const runId = Date.now();
         const transports: LogTransport[] = [];
-        const logsPath = getLogsPath(directories.log, options.space, options.path);
+        const logsPath = resolveCommandPath(directories.log, options.space, options.path);
         const logFilename = `${commandPieces.join('-')}-${runId}.jsonl`;
         const filePath = path.join(logsPath, logFilename);
         transports.push(new FileTransport({
@@ -68,6 +71,16 @@ export function getProgram(): Command {
         });
 
         getUI({ enabled: true });
+
+        const reportPath = resolveCommandPath(directories.report, options.space, options.path);
+        const reportFilename = `${commandPieces.join('-')}-${runId}.jsonl`;
+        const reportFilePath = path.join(reportPath, reportFilename);
+        getReporter({ enabled: true, filePath: reportFilePath })
+          .addMeta('command', command)
+          .addMeta('cliVersion', packageJson.version)
+          .addMeta('runId', String(runId))
+          .addMeta('logPath', filePath)
+          .addMeta('config', options);
       });
 
     // Global error handling
diff --git a/packages/cli/src/utils/filesystem.ts b/packages/cli/src/utils/filesystem.ts
@@ -3,7 +3,7 @@ import { appendFile, mkdir, readFile as readFileImpl, writeFile } from 'node:fs/
 import { handleFileSystemError } from './error/filesystem-error';
 import type { FileReaderResult } from '../types';
 import filenamify from 'filenamify';
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
 
 export interface FileOptions {
   mode?: number;
@@ -39,6 +39,28 @@ export const saveToFile = async (filePath: string, data: string, options?: FileO
   }
 };
 
+export const saveToFileSync = (filePath: string, data: string, options?: FileOptions) => {
+  const resolvedPath = parse(filePath).dir;
+
+  // Only attempt to create a directory if there's a directory part
+  if (resolvedPath) {
+    try {
+      mkdirSync(resolvedPath, { recursive: true });
+    }
+    catch (mkdirError) {
+      handleFileSystemError('mkdir', mkdirError as Error);
+      return; // Exit early if the directory creation fails
+    }
+  }
+
+  try {
+    writeFileSync(filePath, data, options as any);
+  }
+  catch (writeError) {
+    handleFileSystemError('write', writeError as Error);
+  }
+};
+
 export const appendToFile = async (filePath: string, data: string, options?: FileOptions) => {
   const resolvedPath = parse(filePath).dir;
 
@@ -99,6 +121,23 @@ export const resolvePath = (path: string | undefined, folder: string) => {
   return resolve(resolve(process.cwd(), '.storyblok'), folder);
 };
 
+/**
+ * Resolves the absolute path for a specific command directory.
+ *
+ * If a `space` is provided, it is appended to the `commandPath` before resolution.
+ *
+ * @param commandPath - The relative path or name of the command category.
+ * @param space - (Optional).
+ * @param baseDir - (Optional) The base directory to resolve against.
+ * @returns The fully resolved absolute path string.
+ */
+export function resolveCommandPath(commandPath: string, space?: string, baseDir?: string) {
+  if (space) {
+    return resolvePath(baseDir, join(commandPath, space));
+  }
+  return resolvePath(baseDir, commandPath);
+}
+
 /**
  * Extracts the component name from a migration filename
  * @param filename - The migration filename (e.g., "simple_component.js")
@@ -138,10 +177,3 @@ export async function readJsonFile<T>(filePath: string): Promise<FileReaderResul
 export function importModule(filePath: string) {
   return import(`file://${filePath}`);
 }
-
-export function getLogsPath(logFileDir: string, space?: string, baseDir?: string) {
-  if (space) {
-    return resolvePath(baseDir, join(logFileDir, space));
-  }
-  return resolvePath(baseDir, logFileDir);
-}
diff --git a/packages/cli/src/utils/reporter.test.ts b/packages/cli/src/utils/reporter.test.ts
diff --git a/packages/cli/src/utils/reporter.ts b/packages/cli/src/utils/reporter.ts
