@livestore/utils-dev 0.4.0-dev.18 → 0.4.0-dev.19

package/src/node/cmd.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs'
 
-import { isNotUndefined, shouldNeverHappen } from '@livestore/utils'
+import { isNotUndefined } from '@livestore/utils'
 import {
   Cause,
   Command,
@@ -19,6 +19,7 @@ import {
 } from '@livestore/utils/effect'
 import { applyLoggingToCommand } from './cmd-log.ts'
 import * as FileLogger from './FileLogger.ts'
+import { CurrentWorkingDirectory } from './workspace.ts'
 
 // Branded zero value so we can compare exit codes without touching internals.
 const SUCCESS_EXIT_CODE: CommandExecutor.ExitCode = 0 as CommandExecutor.ExitCode
@@ -27,7 +28,6 @@ export const cmd: (
   commandInput: string | (string | undefined)[],
   options?:
     | {
-        cwd?: string
         stderr?: 'inherit' | 'pipe'
         stdout?: 'inherit' | 'pipe'
         shell?: boolean
@@ -43,84 +43,86 @@ export const cmd: (
         logRetention?: number
       }
     | undefined,
-) => Effect.Effect<CommandExecutor.ExitCode, PlatformError.PlatformError | CmdError, CommandExecutor.CommandExecutor> =
-  Effect.fn('cmd')(function* (commandInput, options) {
-    const cwd = options?.cwd ?? process.env.WORKSPACE_ROOT ?? shouldNeverHappen('WORKSPACE_ROOT is not set')
-
-    const asArray = Array.isArray(commandInput)
-    const parts = asArray ? (commandInput as (string | undefined)[]).filter(isNotUndefined) : undefined
-    const [command, ...args] = asArray ? (parts as string[]) : (commandInput as string).split(' ')
-
-    const debugEnvStr = Object.entries(options?.env ?? {})
-      .map(([key, value]) => `${key}='${value}' `)
-      .join('')
-
-    const loggingOpts = {
-      ...(options?.logDir ? { logDir: options.logDir } : {}),
-      ...(options?.logFileName ? { logFileName: options.logFileName } : {}),
-      ...(options?.logRetention ? { logRetention: options.logRetention } : {}),
-    } as const
-    const { input: finalInput, subshell: needsShell, logPath } = yield* applyLoggingToCommand(commandInput, loggingOpts)
-
-    const stdoutMode = options?.stdout ?? 'inherit'
-    const stderrMode = options?.stderr ?? 'inherit'
-    const useShell = (options?.shell ? true : false) || needsShell
-
-    const commandDebugStr =
-      debugEnvStr + (Array.isArray(finalInput) ? (finalInput as string[]).join(' ') : (finalInput as string))
-    const subshellStr = useShell ? ' (in subshell)' : ''
-
-    yield* Effect.logDebug(`Running '${commandDebugStr}' in '${cwd}'${subshellStr}`)
-    yield* Effect.annotateCurrentSpan({
-      'span.label': commandDebugStr,
-      cwd,
-      command,
-      args,
-      logDir: options?.logDir,
-    })
+) => Effect.Effect<
+  CommandExecutor.ExitCode,
+  PlatformError.PlatformError | CmdError,
+  CommandExecutor.CommandExecutor | CurrentWorkingDirectory
+> = Effect.fn('cmd')(function* (commandInput, options) {
+  const cwd = yield* CurrentWorkingDirectory
+
+  const asArray = Array.isArray(commandInput)
+  const parts = asArray ? (commandInput as (string | undefined)[]).filter(isNotUndefined) : undefined
+  const [command, ...args] = asArray ? (parts as string[]) : (commandInput as string).split(' ')
+
+  const debugEnvStr = Object.entries(options?.env ?? {})
+    .map(([key, value]) => `${key}='${value}' `)
+    .join('')
+
+  const loggingOpts = {
+    ...(options?.logDir ? { logDir: options.logDir } : {}),
+    ...(options?.logFileName ? { logFileName: options.logFileName } : {}),
+    ...(options?.logRetention ? { logRetention: options.logRetention } : {}),
+  } as const
+  const { input: finalInput, subshell: needsShell, logPath } = yield* applyLoggingToCommand(commandInput, loggingOpts)
+
+  const stdoutMode = options?.stdout ?? 'inherit'
+  const stderrMode = options?.stderr ?? 'inherit'
+  const useShell = (options?.shell ? true : false) || needsShell
+
+  const commandDebugStr =
+    debugEnvStr + (Array.isArray(finalInput) ? (finalInput as string[]).join(' ') : (finalInput as string))
+  const subshellStr = useShell ? ' (in subshell)' : ''
+
+  yield* Effect.logDebug(`Running '${commandDebugStr}' in '${cwd}'${subshellStr}`)
+  yield* Effect.annotateCurrentSpan({
+    'span.label': commandDebugStr,
+    cwd,
+    command,
+    args,
+    logDir: options?.logDir,
+  })
 
-    const baseArgs = {
-      commandInput: finalInput,
-      cwd,
-      env: options?.env ?? {},
-      stdoutMode,
-      stderrMode,
-      useShell,
-    } as const
-
-    const exitCode = yield* isNotUndefined(logPath)
-      ? Effect.gen(function* () {
-          yield* Effect.sync(() => console.log(`Logging output to ${logPath}`))
-          return yield* runWithLogging({ ...baseArgs, logPath, threadName: commandDebugStr })
-        })
-      : runWithoutLogging(baseArgs)
-
-    if (exitCode !== SUCCESS_EXIT_CODE) {
-      return yield* Effect.fail(
-        CmdError.make({
-          command: command!,
-          args,
-          cwd,
-          env: options?.env ?? {},
-          stderr: stderrMode,
-        }),
-      )
-    }
+  const baseArgs = {
+    commandInput: finalInput,
+    cwd,
+    env: options?.env ?? {},
+    stdoutMode,
+    stderrMode,
+    useShell,
+  } as const
+
+  const exitCode = yield* isNotUndefined(logPath)
+    ? Effect.gen(function* () {
+        yield* Effect.sync(() => console.log(`Logging output to ${logPath}`))
+        return yield* runWithLogging({ ...baseArgs, logPath, threadName: commandDebugStr })
+      })
+    : runWithoutLogging(baseArgs)
+
+  if (exitCode !== SUCCESS_EXIT_CODE) {
+    return yield* Effect.fail(
+      CmdError.make({
+        command: command!,
+        args,
+        cwd,
+        env: options?.env ?? {},
+        stderr: stderrMode,
+      }),
+    )
+  }
 
-    return exitCode
-  })
+  return exitCode
+})
 
 export const cmdText: (
   commandInput: string | (string | undefined)[],
   options?: {
-    cwd?: string
     stderr?: 'inherit' | 'pipe'
     runInShell?: boolean
     env?: Record<string, string | undefined>
   },
-) => Effect.Effect<string, PlatformError.PlatformError, CommandExecutor.CommandExecutor> = Effect.fn('cmdText')(
-  function* (commandInput, options) {
-    const cwd = options?.cwd ?? process.env.WORKSPACE_ROOT ?? shouldNeverHappen('WORKSPACE_ROOT is not set')
+) => Effect.Effect<string, PlatformError.PlatformError, CommandExecutor.CommandExecutor | CurrentWorkingDirectory> =
+  Effect.fn('cmdText')(function* (commandInput, options) {
+    const cwd = yield* CurrentWorkingDirectory
     const [command, ...args] = Array.isArray(commandInput)
       ? commandInput.filter(isNotUndefined)
       : commandInput.split(' ')
@@ -142,8 +144,7 @@ export const cmdText: (
       Command.env(options?.env ?? {}),
       Command.string,
     )
-  },
-)
+  })
 
 export class CmdError extends Schema.TaggedError<CmdError>()('CmdError', {
   command: Schema.String,

package/src/node/mod.ts

@@ -24,6 +24,7 @@ export {
   startDockerComposeServicesScoped,
 } from './DockerComposeService/DockerComposeService.ts'
 export * as FileLogger from './FileLogger.ts'
+export * from './workspace.ts'
 
 export const OtelLiveHttp = ({
   serviceName,

package/src/node/workspace.ts

@@ -0,0 +1,45 @@
+import path from 'node:path'
+import { shouldNeverHappen } from '@livestore/utils'
+import { Context, Effect, Layer } from '@livestore/utils/effect'
+
+export type WorkspaceInfo = string
+
+/** Current working directory. */
+export class CurrentWorkingDirectory extends Context.Tag('CurrentWorkingDirectory')<
+  CurrentWorkingDirectory,
+  WorkspaceInfo
+>() {
+  /** Layer that captures the process cwd once. */
+  static live = Layer.effect(
+    CurrentWorkingDirectory,
+    Effect.sync(() => process.cwd()),
+  )
+
+  /** Override CWD for tests or nested invocations. */
+  static fromPath = (cwd: string) => Layer.succeed(CurrentWorkingDirectory, cwd)
+}
+
+/** Livestore workspace root (env required). */
+export class LivestoreWorkspace extends Context.Tag('LivestoreWorkspace')<LivestoreWorkspace, WorkspaceInfo>() {
+  /** Resolve from WORKSPACE_ROOT env. */
+  static live = Layer.effect(
+    LivestoreWorkspace,
+    Effect.sync(() => {
+      const root = process.env.WORKSPACE_ROOT ?? shouldNeverHappen('WORKSPACE_ROOT is not set')
+      return root
+    }),
+  )
+
+  /** Provide a fixed Livestore root. */
+  static fromPath = (root: string) => Layer.succeed(LivestoreWorkspace, root)
+
+  /** Derive a CurrentWorkingDirectory layer from the Livestore workspace root (with optional subpath) */
+  static toCwd = (/** Relative path to the Livestore workspace root */ subPath?: string) =>
+    Layer.effect(
+      CurrentWorkingDirectory,
+      Effect.gen(function* () {
+        const root = yield* LivestoreWorkspace
+        return path.join(root, subPath ?? '')
+      }),
+    )
+}

package/src/wrangler/WranglerDevServer.test.ts

@@ -59,7 +59,7 @@ Vitest.describe('WranglerDevServer', { timeout: testTimeout }, () => {
             WranglerDevServerTest({
               cwd: '/tmp',
               wranglerConfigPath: '/dev/null',
-              connectTimeout: '500 millis',
+              readiness: { connectTimeout: '500 millis' },
             }).pipe(Layer.provide(PlatformNode.NodeContext.layer)),
           ),
           Effect.flip,

package/src/wrangler/WranglerDevServer.ts

@@ -24,17 +24,35 @@ export interface WranglerDevServer {
 }
 
 /**
- * Configuration for starting WranglerDevServer
+ * Readiness and retry configuration for wrangler boot and HTTP health.
+ *
+ * Example: startupTimeout=20s, connectTimeout=5s, retrySchedule=recurs(1)
+ * - Give wrangler up to 20s to boot; if it succeeds, give the HTTP check up to 5s.
+ * - If wrangler fails/times out, retry boot once; each boot attempt gets its own 20s budget.
+ * connectTimeout should be shorter than startupTimeout because HTTP readiness should be fast after boot.
  */
+export interface WranglerReadinessOptions {
+  /** Max time to wait for wrangler to report ready before retrying. */
+  startupTimeout?: Duration.DurationInput
+  /** Max time for the HTTP connectivity check after wrangler reports ready. */
+  connectTimeout?: Duration.DurationInput
+  /** Retry policy for startup attempts (applies when startupTimeout elapses or wrangler throws). */
+  retrySchedule?: Schedule.Schedule<unknown, unknown, never>
+}
+
 export interface StartWranglerDevServerArgs {
+  /** Path to wrangler.toml (defaults to cwd/wrangler.toml). */
   wranglerConfigPath?: string
+  /** Working directory wrangler should use. */
   cwd: string
   /** The port to try first. The dev server may bind a different port if unavailable. */
   preferredPort?: number
   /** @default false */
   showLogs?: boolean
+  /** Optional inspector port for wrangler dev. */
   inspectorPort?: number
-  connectTimeout?: Duration.DurationInput
+  /** Readiness and retry configuration for bringing up wrangler and confirming connectivity. */
+  readiness?: WranglerReadinessOptions
 }
 
 /**
@@ -74,6 +92,8 @@ export class WranglerDevServerService extends Effect.Service<WranglerDevServerSe
       )
       const resolvedMainPath = yield* Effect.try(() => path.resolve(args.cwd, parsedConfig.main))
 
+      const readiness = args.readiness ?? {}
+      const startupTimeout = readiness.startupTimeout ?? Duration.seconds(IS_CI ? 30 : 10)
       const devServer = yield* Effect.promise(() =>
         wrangler.unstable_dev(resolvedMainPath, {
           config: configPath,
@@ -85,6 +105,24 @@ export class WranglerDevServerService extends Effect.Service<WranglerDevServerSe
             disableExperimentalWarning: true,
           },
         }),
+      ).pipe(
+        Effect.timeout(startupTimeout),
+        Effect.mapError(
+          (cause) =>
+            new WranglerDevServerError({
+              cause,
+              message: `Failed to start wrangler dev server within ${Duration.format(startupTimeout)}`,
+              port: preferredPort,
+            }),
+        ),
+        Effect.tapError((error) =>
+          Effect.logError('Wrangler dev server failed to start', {
+            message: error.message,
+            preferredPort,
+            cwd: args.cwd,
+          }),
+        ),
+        Effect.retry(readiness.retrySchedule ?? Schedule.recurs(1)),
       )
 
       yield* Effect.addFinalizer(
@@ -111,10 +149,11 @@ export class WranglerDevServerService extends Effect.Service<WranglerDevServerSe
       const actualHost = devServer.address
       const url = `http://${actualHost}:${actualPort}`
 
-      // Use longer timeout in CI environments to account for slower startup times
-      const defaultTimeout = Duration.seconds(IS_CI ? 30 : 5)
+      // Use longer timeout in CI environments to account for slower HTTP readiness
+      const defaultConnectivityTimeout = Duration.seconds(IS_CI ? 30 : 5)
+      const connectivityTimeout = readiness.connectTimeout ?? defaultConnectivityTimeout
 
-      yield* verifyHttpConnectivity({ url, showLogs, connectTimeout: args.connectTimeout ?? defaultTimeout })
+      yield* verifyHttpConnectivity({ url, showLogs, connectTimeout: connectivityTimeout })
 
       if (showLogs) {
         yield* Effect.logDebug(
@@ -127,9 +166,10 @@ export class WranglerDevServerService extends Effect.Service<WranglerDevServerSe
         url,
       } satisfies WranglerDevServer
     }).pipe(
-      Effect.mapError(
-        (error) =>
-          new WranglerDevServerError({ cause: error, message: 'Failed to start wrangler dev server', port: -1 }),
+      Effect.mapError((error) =>
+        error instanceof WranglerDevServerError
+          ? error
+          : new WranglerDevServerError({ cause: error, message: 'Failed to start wrangler dev server', port: -1 }),
       ),
       Effect.withSpan('WranglerDevServerService', {
         attributes: { preferredPort: args.preferredPort ?? 'auto', cwd: args.cwd },