feat(cli): implement console and file loggers for migrations (#372)

Fixes WDX-189

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Introduces a structured console/file logger wired into migrations
(generate/run/rollback) with run-scoped JSONL files and a new `logs`
command to list/prune them.
> 
> - **Logging infrastructure**
>   - **New logger**: Adds `utils/logger` with pluggable transports.
> - **File/Console transports**: Implement `logger-transport-file`
(JSONL, max-files pruning, list/prune helpers) and
`logger-transport-console` (formatted output) with tests.
> - **Program bootstrap**: Initialize logger per run in `program.ts`
(per-command JSONL file under `logs/<space>`), enable UI.
> - **Filesystem utils**: Add `importModule`, `getLogsPath`,
`appendToFileSync`.
>   - **Error utils**: Add `toError`; pipe errors to logger.
> - **Migrations commands**
> - **Run**: Replace konsola/progress with `UI`; log lifecycle and
summaries; improved pipelines and error codes; summaries via UI.
>   - **Generate**: Use `UI` + logger; spinner + success path logged.
> - **Rollback**: Use `UI` + logger; per-story spinners; result summary
logged.
> - **Streams/Actions**: Dynamic module import via `importModule`;
detailed logging and standardized error codes.
> - **Logs CLI**
> - **Command `logs`**: New `list` and `prune` subcommands operating on
`logs/<space>` via `FileTransport` helpers; usage docs.
> - **Constants/Index**
> - Add `commands.LOGS`, `directories.log`, wire command in CLI entry;
update color palette.
> - **Tests**
> - Add/adjust tests for logger transports, logs command, and migrations
flows (logging, dry-run, errors).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
1760ea3. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: maoberlehner

packages/cli/.gitignore

@@ -7,6 +7,8 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 lerna-debug.log*
+# Exclude the logs command
+!/src/commands/logs
 
 # Diagnostic reports (https://nodejs.org/api/report.html)
 report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

packages/cli/src/commands/logs/README.md

@@ -0,0 +1,26 @@
+# Logs Command
+
+The `logs` command lets you inspect and manage logs.
+
+## Subcommands
+
+### `list`
+
+Show available run artifacts for the selected space.
+
+```bash
+storyblok logs list --space YOUR_SPACE_ID
+```
+
+### `prune`
+
+Delete stored logs.
+
+```bash
+storyblok logs prune --space YOUR_SPACE_ID [--keep <count>]
+```
+
+Options:
+- `--keep <count>` retains the most recent `count` runs and deletes the rest (default `0`, meaning remove all).
+
+Note: use the same `--path` option you used when running the command producing the logs.

packages/cli/src/commands/logs/command.ts

@@ -0,0 +1,11 @@
+import { commands } from '../../constants';
+import { getProgram } from '../../program';
+
+const program = getProgram();
+
+export const logsCommand = program
+  .command(commands.LOGS)
+  .alias('lg')
+  .description(`Inspect and manage logs.`)
+  .option('-s, --space <space>', 'The space ID.')
+  .option('-p, --path <path>', 'Path to the directory containing the logs directory. Defaults to \'.storyblok\'.');

packages/cli/src/commands/logs/index.ts

@@ -0,0 +1,3 @@
+import './command';
+import './list';
+import './prune';

packages/cli/src/commands/logs/list/index.test.ts

@@ -0,0 +1,80 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { vol } from 'memfs';
+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';
+
+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 preconditions = {
+  hasLogFiles() {
+    vol.fromJSON({
+      [path.join(LOGS_FILE_DIR, 'storyblok-migrations-run-1234567890.jsonl')]: 'foo',
+      [path.join(LOGS_FILE_DIR, 'storyblok-migrations-run-1234567891.jsonl')]: 'foo',
+      [path.join(LOGS_FILE_DIR, 'storyblok-components-push-1234567892.jsonl')]: 'foo',
+    });
+  },
+  hasNoLogFiles() {
+    vol.reset();
+  },
+  hasEmptyLogDirectory() {
+    vol.fromJSON({
+      'logs/12345/.gitkeep': '',
+    });
+  },
+};
+
+describe('logs list command', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.clearAllMocks();
+    vol.reset();
+  });
+
+  it('should list available log files', async () => {
+    preconditions.hasLogFiles();
+
+    await logsCommand.parseAsync(['node', 'test', 'list', '--space', '12345']);
+
+    expect(console.info).toHaveBeenCalledWith(
+      expect.stringContaining('Found 3 log files for space "12345":'),
+    );
+    expect(console.log).toHaveBeenCalledWith(
+      expect.stringContaining('storyblok-components-push-1234567892.jsonl'),
+    );
+    expect(console.log).toHaveBeenCalledWith(
+      expect.stringContaining('storyblok-migrations-run-1234567890.jsonl'),
+    );
+    expect(console.log).toHaveBeenCalledWith(
+      expect.stringContaining('storyblok-migrations-run-1234567891.jsonl'),
+    );
+  });
+
+  it('should handle no logs found when directory does not exist', async () => {
+    preconditions.hasNoLogFiles();
+
+    await logsCommand.parseAsync(['node', 'test', 'list', '--space', '12345']);
+
+    expect(console.info).toHaveBeenCalledWith(
+      expect.stringContaining('No logs found for space "12345"'),
+    );
+  });
+
+  it('should handle no logs found when directory is empty', async () => {
+    preconditions.hasEmptyLogDirectory();
+
+    await logsCommand.parseAsync(['node', 'test', 'list', '--space', '12345']);
+
+    expect(console.info).toHaveBeenCalledWith(
+      expect.stringContaining('No logs found for space "12345"'),
+    );
+  });
+});

packages/cli/src/commands/logs/list/index.ts

@@ -0,0 +1,22 @@
+import { getLogsPath } from '../../../utils/filesystem';
+import { getUI } from '../../../utils/ui';
+import { logsCommand } from '../command';
+import { FileTransport } from '../../../utils/logger-transport-file';
+import { directories } from '../../../constants';
+
+logsCommand.command('list')
+  .description('List logs')
+  .action(async () => {
+    const { space, path } = logsCommand.opts();
+    const ui = getUI();
+    const logsPath = getLogsPath(directories.log, space, path);
+    const logFiles = FileTransport.listLogFiles(logsPath);
+
+    if (logFiles.length === 0) {
+      ui.info(`No logs found for space "${space}".`);
+      return;
+    }
+
+    ui.info(`Found ${logFiles.length} log file${logFiles.length === 1 ? '' : 's'} for space "${space}":`);
+    ui.list(logFiles);
+  });

packages/cli/src/commands/logs/prune/index.test.ts

@@ -0,0 +1,85 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { vol } from 'memfs';
+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';
+
+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 preconditions = {
+  hasLogFiles() {
+    vol.fromJSON({
+      [path.join(LOGS_FILE_DIR, 'storyblok-migrations-run-1234567890.jsonl')]: 'foo',
+      [path.join(LOGS_FILE_DIR, 'storyblok-migrations-run-1234567891.jsonl')]: 'foo',
+      [path.join(LOGS_FILE_DIR, 'storyblok-components-push-1234567892.jsonl')]: 'foo',
+    });
+  },
+};
+
+describe('logs prune command', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.clearAllMocks();
+    vol.reset();
+  });
+
+  it('should delete all logs when keep is 0 (default)', async () => {
+    preconditions.hasLogFiles();
+
+    await logsCommand.parseAsync(['node', 'test', 'prune', '--space', '12345']);
+
+    expect(console.info).toHaveBeenCalledWith(
+      expect.stringContaining('Deleted 3 log files'),
+    );
+    const remainingFiles = Object.keys(vol.toJSON())
+      .filter(path => path.includes('.jsonl'));
+    expect(remainingFiles).toHaveLength(0);
+  });
+
+  it('should keep specified number of recent logs', async () => {
+    preconditions.hasLogFiles();
+
+    await logsCommand.parseAsync(['node', 'test', 'prune', '--space', '12345', '--keep', '2']);
+
+    expect(console.info).toHaveBeenCalledWith(
+      expect.stringContaining('Deleted 1 log file'),
+    );
+    const remainingFiles = Object.keys(vol.toJSON())
+      .filter(path => path.includes('.jsonl'));
+    expect(remainingFiles).toHaveLength(2);
+  });
+
+  it('should not delete logs when keep count equals total', async () => {
+    preconditions.hasLogFiles();
+
+    await logsCommand.parseAsync(['node', 'test', 'prune', '--space', '12345', '--keep', '3']);
+
+    expect(console.info).toHaveBeenCalledWith(
+      expect.stringContaining('Deleted 0 log files'),
+    );
+    const remainingFiles = Object.keys(vol.toJSON())
+      .filter(path => path.includes('.jsonl'));
+    expect(remainingFiles).toHaveLength(3);
+  });
+
+  it('should not delete logs when keep count exceeds total', async () => {
+    preconditions.hasLogFiles();
+
+    await logsCommand.parseAsync(['node', 'test', 'prune', '--space', '12345', '--keep', '10']);
+
+    expect(console.info).toHaveBeenCalledWith(
+      expect.stringContaining('Deleted 0 log files'),
+    );
+    const remainingFiles = Object.keys(vol.toJSON())
+      .filter(path => path.includes('.jsonl'));
+    expect(remainingFiles).toHaveLength(3);
+  });
+});

packages/cli/src/commands/logs/prune/index.ts

@@ -0,0 +1,17 @@
+import { getLogsPath } from '../../../utils/filesystem';
+import { getUI } from '../../../utils/ui';
+import { logsCommand } from '../command';
+import { FileTransport } from '../../../utils/logger-transport-file';
+import { directories } from '../../../constants';
+
+logsCommand.command('prune')
+  .description('Prune logs')
+  .option('--keep <number>', 'Max number of log files to keep (default `0`, meaning remove all)', Number.parseInt, 0)
+  .action(async ({ keep }: { keep: number }) => {
+    const { space, path } = logsCommand.opts();
+    const ui = getUI();
+    const logsPath = getLogsPath(directories.log, space, path);
+    const deletedFilesCount = FileTransport.pruneLogFiles(logsPath, keep);
+
+    ui.info(`Deleted ${deletedFilesCount} log file${deletedFilesCount === 1 ? '' : 's'}`);
+  });