@livestore/utils-dev 0.4.0-dev.9 → 0.4.0

package/src/node/DockerComposeService/DockerComposeService.ts

@@ -1,4 +1,4 @@
-import { omitUndefineds } from '@livestore/utils'
+import { objectToString, omitUndefineds } from '@livestore/utils'
 import {
   Command,
   type CommandExecutor,
@@ -12,7 +12,7 @@ import {
   Stream,
 } from '@livestore/utils/effect'
 
-export class DockerComposeError extends Schema.TaggedError<DockerComposeError>()('DockerComposeError', {
+export class DockerComposeError extends Schema.TaggedError<DockerComposeError>('~@livestore/utils-dev/DockerComposeError')('DockerComposeError', {
   cause: Schema.Defect,
   note: Schema.String,
 }) {}
@@ -20,6 +20,8 @@ export class DockerComposeError extends Schema.TaggedError<DockerComposeError>()
 export interface DockerComposeArgs {
   readonly cwd: string
   readonly serviceName?: string
+  /** Unique project name to isolate this compose instance. If not provided, a random one is generated. */
+  readonly projectName?: string
 }
 
 export interface StartOptions {
@@ -52,20 +54,27 @@ export interface DockerComposeOperations {
   readonly logs: (
     options?: LogsOptions,
   ) => Stream.Stream<string, DockerComposeError | PlatformError.PlatformError, Scope.Scope>
+  /** The unique project name used to isolate this compose instance */
+  readonly projectName: string
 }
 
+const generateProjectName = (): string => `ls-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+
 export class DockerComposeService extends Effect.Service<DockerComposeService>()('DockerComposeService', {
   scoped: (args: DockerComposeArgs) =>
     Effect.gen(function* () {
       const { cwd, serviceName } = args
+      const projectName = args.projectName ?? generateProjectName()
 
       const commandExecutorContext = yield* Effect.context<CommandExecutor.CommandExecutor>()
 
+      const baseComposeArgs = ['-p', projectName]
+
       const pull = Effect.gen(function* () {
         yield* Effect.log(`Pulling Docker Compose images in ${cwd}`)
 
         // TODO (@IMax153) Refactor the effect command related code below as there is probably a much more elegant way to accomplish what we want here in a more effect idiomatic way.
-        const pullCommand = Command.make('docker', 'compose', 'pull').pipe(
+        const pullCommand = Command.make('docker', 'compose', ...baseComposeArgs, 'pull').pipe(
           Command.workingDirectory(cwd),
           Command.stdout('pipe'),
           Command.stderr('pipe'),
@@ -118,61 +127,60 @@ export class DockerComposeService extends Effect.Service<DockerComposeService>()
         Effect.scoped,
       )
 
-      const start = (options: StartOptions = {}) =>
-        Effect.gen(function* () {
-          const { detached = true, healthCheck } = options
+      const start = Effect.fn('startDockerCompose')(function* (options: StartOptions = {}) {
+        const { detached = true, healthCheck } = options
 
-          // Build start command
-          const baseArgs = ['docker', 'compose', 'up']
-          if (detached) baseArgs.push('-d')
-          if (serviceName) baseArgs.push(serviceName)
+        // Build start command
+        const startArgs = ['docker', 'compose', ...baseComposeArgs, 'up']
+        if (detached === true) startArgs.push('-d')
+        if (serviceName !== undefined) startArgs.push(serviceName)
 
-          const command = yield* Command.make(baseArgs[0]!, ...baseArgs.slice(1)).pipe(
-            Command.workingDirectory(cwd),
-            Command.env(options.env ?? {}),
-            Command.stderr('inherit'),
-            Command.stdout('inherit'),
-            Command.start,
-            Effect.catchAll((cause) =>
-              Effect.fail(
-                new DockerComposeError({
-                  cause,
-                  note: `Failed to start Docker Compose services in ${cwd}`,
-                }),
-              ),
-            ),
-            Effect.provide(commandExecutorContext),
-          )
+        const command = yield* Command.make(startArgs[0]!, ...startArgs.slice(1)).pipe(
+          Command.workingDirectory(cwd),
+          Command.env(options.env ?? {}),
+          Command.stderr('inherit'),
+          Command.stdout('inherit'),
+          Command.start,
+          Effect.mapError(
+            (cause) =>
+              new DockerComposeError({
+                cause,
+                note: `Failed to start Docker Compose services in ${cwd}`,
+              }),
+          ),
+          Effect.provide(commandExecutorContext),
+        )
 
-          // Wait for command completion
-          yield* command.exitCode.pipe(
-            Effect.flatMap((exitCode) =>
-              exitCode === 0
-                ? Effect.void
-                : Effect.fail(
-                    new DockerComposeError({
-                      cause: new Error(`Docker compose exited with code ${exitCode}`),
-                      note: `Docker Compose failed to start with exit code ${exitCode}. Env: ${JSON.stringify(options.env)}`,
-                    }),
-                  ),
-            ),
-            Effect.provide(commandExecutorContext),
-          )
+        // Wait for command completion
+        yield* command.exitCode.pipe(
+          Effect.flatMap((exitCode) =>
+            exitCode === 0
+              ? Effect.void
+              : Effect.fail(
+                  new DockerComposeError({
+                    cause: new Error(`Docker compose exited with code ${exitCode}`),
+                    note: `Docker Compose failed to start with exit code ${exitCode}. Env: ${JSON.stringify(options.env)}`,
+                  }),
+                ),
+          ),
+          Effect.provide(commandExecutorContext),
+        )
 
-          // Perform health check if requested
-          if (healthCheck) {
-            yield* performHealthCheck(healthCheck).pipe(Effect.provide(commandExecutorContext))
-          }
+        // Perform health check if requested
+        if (healthCheck !== undefined) {
+          yield* performHealthCheck(healthCheck).pipe(Effect.provide(commandExecutorContext))
+        }
 
-          yield* Effect.log(`Docker Compose services started successfully in ${cwd}`)
-        }).pipe(Effect.withSpan('startDockerCompose'))
+        yield* Effect.log(`Docker Compose services started successfully in ${cwd}`)
+      })
 
       const stop = Effect.gen(function* () {
         yield* Effect.log(`Stopping Docker Compose services in ${cwd}`)
 
-        const stopCommand = serviceName
-          ? Command.make('docker', 'compose', 'stop', serviceName)
-          : Command.make('docker', 'compose', 'stop')
+        const stopCommand =
+          serviceName !== undefined
+            ? Command.make('docker', 'compose', ...baseComposeArgs, 'stop', serviceName)
+            : Command.make('docker', 'compose', ...baseComposeArgs, 'stop')
 
         yield* stopCommand.pipe(
           Command.workingDirectory(cwd),
@@ -197,22 +205,21 @@ export class DockerComposeService extends Effect.Service<DockerComposeService>()
         Effect.gen(function* () {
           const { follow = false, tail, since } = options
 
-          const baseArgs = ['docker', 'compose', 'logs']
-          if (follow) baseArgs.push('-f')
-          if (tail) baseArgs.push('--tail', tail.toString())
-          if (since) baseArgs.push('--since', since)
-          if (serviceName) baseArgs.push(serviceName)
+          const logsArgs = ['docker', 'compose', ...baseComposeArgs, 'logs']
+          if (follow === true) logsArgs.push('-f')
+          if (tail !== undefined) logsArgs.push('--tail', tail.toString())
+          if (since !== undefined) logsArgs.push('--since', since)
+          if (serviceName !== undefined) logsArgs.push(serviceName)
 
-          const command = yield* Command.make(baseArgs[0]!, ...baseArgs.slice(1)).pipe(
+          const command = yield* Command.make(logsArgs[0]!, ...logsArgs.slice(1)).pipe(
             Command.workingDirectory(cwd),
             Command.start,
-            Effect.catchAll((cause) =>
-              Effect.fail(
+            Effect.mapError(
+              (cause) =>
                 new DockerComposeError({
                   cause,
                   note: `Failed to read Docker Compose logs in ${cwd}`,
                 }),
-              ),
             ),
             Effect.provide(commandExecutorContext),
           )
@@ -230,40 +237,49 @@ export class DockerComposeService extends Effect.Service<DockerComposeService>()
           )
         }).pipe(Stream.unwrapScoped)
 
-      const down = (options?: {
+      const down = Effect.fn('downDockerCompose')(function* (options?: {
         readonly env?: Record<string, string>
         readonly volumes?: boolean
         readonly removeOrphans?: boolean
-      }) =>
-        Effect.gen(function* () {
-          yield* Effect.log(`Tearing down Docker Compose services in ${cwd}`)
+      }) {
+        yield* Effect.log(`Tearing down Docker Compose services in ${cwd}`)
 
-          const baseArgs = ['docker', 'compose', 'down']
-          if (options?.volumes) baseArgs.push('-v')
-          if (options?.removeOrphans) baseArgs.push('--remove-orphans')
-          if (serviceName) baseArgs.push(serviceName)
+        const downArgs = ['docker', 'compose', ...baseComposeArgs, 'down']
+        if (options?.volumes === true) downArgs.push('-v')
+        if (options?.removeOrphans === true) downArgs.push('--remove-orphans')
+        if (serviceName !== undefined) downArgs.push(serviceName)
 
-          yield* Command.make(baseArgs[0]!, ...baseArgs.slice(1)).pipe(
-            Command.workingDirectory(cwd),
-            Command.env(options?.env ?? {}),
-            Command.exitCode,
-            Effect.flatMap((exitCode: number) =>
-              exitCode === 0
-                ? Effect.void
-                : Effect.fail(
-                    new DockerComposeError({
-                      cause: new Error(`Docker compose down exited with code ${exitCode}`),
-                      note: `Failed to tear down Docker Compose services`,
-                    }),
-                  ),
-            ),
-            Effect.provide(commandExecutorContext),
-          )
+        yield* Command.make(downArgs[0]!, ...downArgs.slice(1)).pipe(
+          Command.workingDirectory(cwd),
+          Command.env(options?.env ?? {}),
+          Command.exitCode,
+          Effect.flatMap((exitCode: number) =>
+            exitCode === 0
+              ? Effect.void
+              : Effect.fail(
+                  new DockerComposeError({
+                    cause: new Error(`Docker compose down exited with code ${exitCode}`),
+                    note: `Failed to tear down Docker Compose services`,
+                  }),
+                ),
+          ),
+          Effect.provide(commandExecutorContext),
+        )
+
+        yield* Effect.log(`Docker Compose services torn down successfully`)
+      })
 
-          yield* Effect.log(`Docker Compose services torn down successfully`)
-        }).pipe(Effect.withSpan('downDockerCompose'))
+      // Register cleanup finalizer to ensure containers are removed when scope closes
+      yield* Effect.addFinalizer(() =>
+        down({ volumes: true, removeOrphans: true }).pipe(
+          Effect.tap(() => Effect.log(`Docker Compose cleanup completed for project ${projectName}`)),
+          Effect.catchAll((error) =>
+            Effect.log('Docker Compose cleanup failed for project', projectName, objectToString(error)),
+          ),
+        ),
+      )
 
-      return { pull, start, stop, down, logs }
+      return { pull, start, stop, down, logs, projectName }
     }),
 }) {}
 
@@ -287,17 +303,16 @@ const performHealthCheck = ({
 
     const healthCheck = checkHealth.pipe(
       Effect.repeat({
-        while: (healthy: boolean) => !healthy,
+        while: (healthy: boolean) => healthy === false,
         schedule: Schedule.fixed(interval),
       }),
       Effect.timeout(timeout),
-      Effect.catchAll(() =>
-        Effect.fail(
+      Effect.mapError(
+        () =>
           new DockerComposeError({
             cause: new Error('Health check timeout'),
             note: `Health check failed for ${url} after ${Duration.toMillis(timeout)}ms`,
           }),
-        ),
       ),
     )
 
@@ -320,7 +335,7 @@ export const startDockerComposeServicesScoped = (
 
     // Start the services
     yield* dockerCompose.start({
-      ...omitUndefineds({ healthCheck: args.healthCheck ? args.healthCheck : undefined }),
+      ...omitUndefineds({ healthCheck: args.healthCheck !== undefined ? args.healthCheck : undefined }),
     })
 
     // Add cleanup finalizer to the current scope

package/src/node/DockerComposeService/test-fixtures/docker-compose.yml

@@ -1,4 +1,4 @@
 services:
   hello-world:
     image: hello-world
-    profiles: [manual] # Don't auto-start this service
+    profiles: [manual] # Don't auto-start this service

package/src/node/FileLogger.ts

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs'
 import path from 'node:path'
 import util from 'node:util'
+
 import {
   Cause,
   Effect,
@@ -120,7 +121,7 @@ export const prettyLoggerTty = (options: {
   readonly formatDate: (date: Date) => string
   readonly onLog?: (str: string) => void
 }) => {
-  const color = options.colors ? withColor : withColorNoop
+  const color = options.colors === true ? withColor : withColorNoop
   return Logger.make<unknown, string>(({ annotations, cause, date, fiberId, logLevel, message: message_, spans }) => {
     let str = ''
 
@@ -141,7 +142,7 @@ export const prettyLoggerTty = (options: {
       ` ${color(logLevel.label, ...logLevelColors[logLevel._tag])}` +
       ` (${FiberId.threadName(fiberId)})`
 
-    if (List.isCons(spans)) {
+    if (List.isCons(spans) === true) {
       const now = date.getTime()
       const render = LogSpan.render(now)
       for (const span of spans) {
@@ -162,7 +163,7 @@ export const prettyLoggerTty = (options: {
     log(firstLine)
     // if (!processIsBun) console.group()
 
-    if (!Cause.isEmpty(cause)) {
+    if (Cause.isEmpty(cause) === false) {
       logIndented(Cause.pretty(cause, { renderErrorCause: true }))
     }
 

package/src/node/cmd-log.ts

@@ -0,0 +1,84 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { isNotUndefined } from '@livestore/utils'
+import { Effect } from '@livestore/utils/effect'
+
+export type TCmdLoggingOptions = {
+  readonly logDir?: string
+  readonly logFileName?: string
+  readonly logRetention?: number
+}
+
+/**
+ * Prepares logging directories, archives previous canonical log and prunes archives.
+ * Returns the canonical current log path if logging is enabled, otherwise undefined.
+ */
+export const prepareCmdLogging: (options: TCmdLoggingOptions) => Effect.Effect<string | undefined> = Effect.fn(
+  'cmd.logging.prepare',
+)(function* ({ logDir, logFileName = 'dev.log', logRetention = 50 }: TCmdLoggingOptions) {
+  if (logDir == null || logDir === '') return undefined as string | undefined
+
+  const logsDir = logDir
+  const archiveDir = path.join(logsDir, 'archive')
+  const currentLogPath = path.join(logsDir, logFileName)
+
+  // Ensure directories exist
+  yield* Effect.sync(() => fs.mkdirSync(archiveDir, { recursive: true }))
+
+  // Archive previous log if present
+  if (fs.existsSync(currentLogPath) === true) {
+    const safeIso = new Date().toISOString().replaceAll(':', '-')
+    const archivedBase = `${path.parse(logFileName).name}-${safeIso}.log`
+    const archivedLog = path.join(archiveDir, archivedBase)
+    yield* Effect.try(() => fs.renameSync(currentLogPath, archivedLog)).pipe(
+      Effect.catchAll(() =>
+        Effect.try(() => {
+          fs.copyFileSync(currentLogPath, archivedLog)
+          fs.truncateSync(currentLogPath, 0)
+        }),
+      ),
+      Effect.ignore,
+    )
+
+    // Prune archives to retain only the newest N
+    yield* Effect.try(() => fs.readdirSync(archiveDir)).pipe(
+      Effect.map((names) => names.filter((n) => n.endsWith('.log'))),
+      Effect.map((names) =>
+        names
+          .map((name) => ({ name, mtimeMs: fs.statSync(path.join(archiveDir, name)).mtimeMs }))
+          .sort((a, b) => b.mtimeMs - a.mtimeMs),
+      ),
+      Effect.flatMap((entries) =>
+        Effect.forEach(entries.slice(logRetention), (e) =>
+          Effect.try(() => fs.unlinkSync(path.join(archiveDir, e.name))).pipe(Effect.ignore),
+        ),
+      ),
+      Effect.ignore,
+    )
+  }
+
+  return currentLogPath
+})
+
+/**
+ * Given a command input, applies logging by piping output through `tee` to the
+ * canonical log file. Returns the transformed input and whether a shell is required.
+ */
+export const applyLoggingToCommand: (
+  commandInput: string | (string | undefined)[],
+  options: TCmdLoggingOptions,
+) => Effect.Effect<{ input: string | string[]; subshell: boolean; logPath?: string }> = Effect.fn('cmd.logging.apply')(
+  function* (commandInput, options) {
+    const asArray = Array.isArray(commandInput)
+    const parts = asArray === true ? commandInput.filter(isNotUndefined) : undefined
+
+    const logPath = yield* prepareCmdLogging(options)
+
+    return {
+      input: asArray === true ? ((parts as string[]) ?? []) : commandInput,
+      subshell: false,
+      ...(logPath !== undefined ? { logPath } : {}),
+    }
+  },
+)

package/src/node/cmd.test.ts

@@ -0,0 +1,134 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { CommandExecutor, Duration, Effect, Layer } from '@livestore/utils/effect'
+import { PlatformNode } from '@livestore/utils/node'
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { expect } from 'vitest'
+
+import { cmd } from './cmd.ts'
+import { CurrentWorkingDirectory } from './workspace.ts'
+
+const withNode = Vitest.makeWithTestCtx({
+  makeLayer: () => Layer.mergeAll(PlatformNode.NodeContext.layer, CurrentWorkingDirectory.live),
+  timeout: 20_000,
+})
+
+Vitest.describe('cmd helper', () => {
+  const ansiRegex = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g')
+
+  Vitest.scopedLive('runs tokenized string without shell', (test) =>
+    Effect.gen(function* () {
+      const exit = yield* cmd('printf ok')
+      expect(exit).toBe(CommandExecutor.ExitCode(0))
+    }).pipe(withNode(test)),
+  )
+
+  Vitest.scopedLive('runs array input', (test) =>
+    Effect.gen(function* () {
+      const exit = yield* cmd(['printf', 'ok'])
+      expect(exit).toBe(CommandExecutor.ExitCode(0))
+    }).pipe(withNode(test)),
+  )
+
+  /** TODO(#1020): Investigate CI timeout flakiness for cmd tests that spawn many child processes */
+  Vitest.scopedLive(
+    'supports logging with archive + retention',
+    (test) =>
+      Effect.gen(function* () {
+        const workspace = process.env.WORKSPACE_ROOT!
+        const logsDir = path.join(workspace, 'tmp', 'cmd-tests', String(Date.now()))
+
+        // first run
+        const exit1 = yield* cmd('printf first', { logDir: logsDir })
+        expect(exit1).toBe(CommandExecutor.ExitCode(0))
+        const current = path.join(logsDir, 'dev.log')
+        expect(fs.existsSync(current)).toBe(true)
+        const firstLog = fs.readFileSync(current, 'utf8')
+        const firstStdoutLines = firstLog.split('\n').filter((line) => line.includes('[stdout]'))
+        expect(firstStdoutLines.length).toBeGreaterThan(0)
+        for (const line of firstStdoutLines) {
+          expect(line).toContain('[stdout] first')
+          expect(line).toContain('INFO')
+          expect(line).toContain('printf first')
+        }
+
+        // second run — archives previous
+        const exit2 = yield* cmd('printf second', { logDir: logsDir })
+        expect(exit2).toBe(CommandExecutor.ExitCode(0))
+        const archiveDir = path.join(logsDir, 'archive')
+        const archives = fs.readdirSync(archiveDir).filter((f) => f.endsWith('.log'))
+        expect(archives.length).toBe(1)
+        const archivedPath = path.join(archiveDir, archives[0]!)
+        const archivedLog = fs.readFileSync(archivedPath, 'utf8')
+        const archivedStdoutLines = archivedLog.split('\n').filter((line) => line.includes('[stdout]'))
+        expect(archivedStdoutLines.length).toBeGreaterThan(0)
+        for (const line of archivedStdoutLines) {
+          expect(line).toContain('[stdout] first')
+        }
+
+        const secondLog = fs.readFileSync(current, 'utf8')
+        const secondStdoutLines = secondLog.split('\n').filter((line) => line.includes('[stdout]'))
+        expect(secondStdoutLines.length).toBeGreaterThan(0)
+        for (const line of secondStdoutLines) {
+          expect(line).toContain('[stdout] second')
+          expect(line).toContain('INFO')
+        }
+
+        // generate many archives to exercise retention (keep 50)
+        for (let i = 0; i < 60; i++) {
+          // Use small unique payloads
+          yield* cmd(['printf', String(i)], { logDir: logsDir })
+        }
+        const archivesAfter = fs.readdirSync(archiveDir).filter((f) => f.endsWith('.log'))
+        expect(archivesAfter.length).toBeLessThanOrEqual(50)
+      }).pipe(withNode(test)),
+    { timeout: 30_000, retry: 3 },
+  )
+
+  Vitest.scopedLive('streams stdout and stderr with logger formatting', (test) =>
+    Effect.gen(function* () {
+      const workspace = process.env.WORKSPACE_ROOT!
+      const logsDir = path.join(workspace, 'tmp', 'cmd-tests', `format-${Date.now()}`)
+
+      const exit = yield* cmd(['node', '-e', "console.log('out'); console.error('err')"], {
+        logDir: logsDir,
+      })
+      expect(exit).toBe(CommandExecutor.ExitCode(0))
+
+      const current = path.join(logsDir, 'dev.log')
+      const logContent = fs.readFileSync(current, 'utf8')
+      expect(logContent).toMatch(/\[stdout] out/)
+      expect(logContent).toMatch(/\[stderr] err/)
+
+      const relevantLines = logContent
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.includes('[stdout]') || line.includes('[stderr]'))
+
+      expect(relevantLines.length).toBeGreaterThanOrEqual(2)
+
+      for (const line of relevantLines) {
+        const stripped = line.replace(ansiRegex, '')
+        expect(stripped.startsWith('[')).toBe(true)
+        expect(stripped).toMatch(/(INFO|WARN)/)
+        expect(stripped).toMatch(/\[(stdout|stderr)]/)
+      }
+    }).pipe(withNode(test)),
+  )
+
+  Vitest.scopedLive('cleans up logged child process when interrupted', (test) =>
+    Effect.gen(function* () {
+      const workspace = process.env.WORKSPACE_ROOT!
+      const logsDir = path.join(workspace, 'tmp', 'cmd-tests', `timeout-${Date.now()}`)
+
+      const result = yield* cmd(['node', '-e', 'setTimeout(() => {}, 5000)'], {
+        logDir: logsDir,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      }).pipe(Effect.timeoutOption(Duration.millis(200)))
+
+      expect(result._tag).toBe('None')
+      expect(fs.existsSync(path.join(logsDir, 'dev.log'))).toBe(true)
+    }).pipe(withNode(test)),
+  )
+})