libretto 0.1.5 → 0.2.1

package/dist/shared/logger/logger.js

@@ -0,0 +1,188 @@
+function generateId() {
+  return Math.random().toString(36).substring(2, 15);
+}
+const defaultLogger = {
+  info(event, data) {
+    console.log(`[INFO] ${event}`, data ?? "");
+  },
+  warn(event, data) {
+    console.warn(`[WARN] ${event}`, data ?? "");
+  },
+  error(event, data) {
+    console.error(`[ERROR] ${event}`, data ?? "");
+  }
+};
+const sinkLifecycleState = /* @__PURE__ */ new WeakMap();
+function getSinkLifecycleState(sink) {
+  const existingState = sinkLifecycleState.get(sink);
+  if (existingState) {
+    return existingState;
+  }
+  const initialState = { closed: false };
+  sinkLifecycleState.set(sink, initialState);
+  return initialState;
+}
+function isSinkClosedOrClosing(sink) {
+  const state = sinkLifecycleState.get(sink);
+  return Boolean(state?.closed || state?.closing);
+}
+async function closeSinkOnce(sink) {
+  if (!sink.close) {
+    return;
+  }
+  const state = getSinkLifecycleState(sink);
+  if (state.closed) {
+    return;
+  }
+  if (state.closing) {
+    return state.closing;
+  }
+  state.closing = (async () => {
+    try {
+      await sink.close?.();
+    } catch {
+    } finally {
+      state.closed = true;
+      state.closing = void 0;
+    }
+  })();
+  return state.closing;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function removeUndefined(data) {
+  if (typeof data === "object" && data !== null) {
+    return Object.fromEntries(
+      Object.entries(data).filter(([_, value]) => value !== void 0)
+    );
+  }
+  return data;
+}
+class Logger {
+  constructor(scopes = [], sinks = [], scopeData = {}) {
+    this.scopes = scopes;
+    this.sinks = sinks;
+    this.scopeData = scopeData;
+    this.prefix = scopes.join(".");
+  }
+  prefix;
+  entry(entry) {
+    this.sinks.forEach((sink) => {
+      if (isSinkClosedOrClosing(sink)) {
+        return;
+      }
+      sink.write({
+        id: generateId(),
+        scope: this.prefix,
+        level: entry.level,
+        event: entry.event,
+        data: removeUndefined({ ...this.scopeData, ...entry.data }),
+        options: entry.options
+      });
+    });
+  }
+  log(event, data, options) {
+    this.entry({ level: "log", event, data, options });
+  }
+  error(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "error",
+      event,
+      data,
+      options
+    });
+    if (dataOrError instanceof Error) {
+      return dataOrError;
+    }
+    if (isObject(dataOrError) && dataOrError.error instanceof Error) {
+      return dataOrError.error;
+    }
+    let message = event;
+    if (data !== void 0) {
+      try {
+        message += "\n" + JSON.stringify(data, void 0, 2);
+      } catch {
+        message += "\n[Unserializable error data]";
+      }
+    }
+    return new Error(message);
+  }
+  warn(event, dataOrError, options) {
+    const data = dataOrError instanceof Error ? {
+      error: {
+        type: dataOrError.constructor.name,
+        message: dataOrError.message,
+        stack: dataOrError.stack || null
+      }
+    } : isObject(dataOrError) && dataOrError.error instanceof Error ? {
+      ...dataOrError,
+      error: {
+        type: dataOrError.error.constructor.name,
+        message: dataOrError.error.message,
+        stack: dataOrError.error.stack || null
+      }
+    } : isObject(dataOrError) ? dataOrError : dataOrError !== void 0 ? { error: dataOrError } : void 0;
+    this.entry({
+      level: "warn",
+      event,
+      data,
+      options
+    });
+  }
+  info(event, data, options) {
+    this.entry({ level: "info", event, data, options });
+  }
+  withScope(scope, context = {}) {
+    return new Logger([...this.scopes, scope], this.sinks, {
+      ...this.scopeData,
+      ...context
+    });
+  }
+  withContext(context) {
+    return new Logger(this.scopes, this.sinks, {
+      ...this.scopeData,
+      ...context
+    });
+  }
+  withSink(sink) {
+    return new Logger(this.scopes, [...this.sinks, sink]);
+  }
+  async flush() {
+    for (let i = this.sinks.length - 1; i >= 0; i--) {
+      const sink = this.sinks[i];
+      if (!sink) continue;
+      if (isSinkClosedOrClosing(sink)) continue;
+      try {
+        await sink.flush?.();
+      } catch {
+      }
+    }
+  }
+  async close() {
+    await this.flush();
+    for (let i = this.sinks.length - 1; i >= 0; i--) {
+      const sink = this.sinks[i];
+      if (!sink) continue;
+      await closeSinkOnce(sink);
+    }
+  }
+}
+export {
+  Logger,
+  defaultLogger
+};

package/dist/shared/logger/sinks.cjs

@@ -0,0 +1,160 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var sinks_exports = {};
+__export(sinks_exports, {
+  createFileLogSink: () => createFileLogSink,
+  jsonlConsoleSink: () => jsonlConsoleSink,
+  prettyConsoleSink: () => prettyConsoleSink
+});
+module.exports = __toCommonJS(sinks_exports);
+var fs = __toESM(require("node:fs"), 1);
+var path = __toESM(require("node:path"), 1);
+function createFileLogSink({
+  filePath
+}) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const writeStream = fs.createWriteStream(filePath, { flags: "a" });
+  return {
+    write: ({ id, scope, level, event, data, options }) => {
+      if (writeStream.destroyed || writeStream.writableEnded) {
+        return;
+      }
+      const timestamp = options?.timestamp || /* @__PURE__ */ new Date();
+      const logEntry = {
+        timestamp: timestamp.toISOString(),
+        id,
+        level,
+        scope,
+        event,
+        data
+      };
+      const jsonLine = JSON.stringify(logEntry) + "\n";
+      try {
+        writeStream.write(jsonLine, (error) => {
+          if (error) {
+            console.error("Failed to write to log file:", error);
+            console[level]({ id, scope, event, data, timestamp });
+          }
+        });
+      } catch (error) {
+        console.error("Failed to write to log file:", error);
+        console[level]({ id, scope, event, data, timestamp });
+      }
+    },
+    flush: () => new Promise((resolve, reject) => {
+      if (!writeStream.writable || writeStream.writableEnded || writeStream.destroyed) {
+        resolve();
+        return;
+      }
+      writeStream.write("", (error) => {
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      });
+    }),
+    close: () => new Promise((resolve) => {
+      if (writeStream.destroyed || writeStream.closed) {
+        resolve();
+        return;
+      }
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      };
+      writeStream.once("finish", done);
+      writeStream.once("close", done);
+      writeStream.once("error", done);
+      try {
+        writeStream.end();
+      } catch {
+        done();
+      }
+    })
+  };
+}
+const colors = {
+  reset: "\x1B[0m",
+  gray: "\x1B[90m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m"
+};
+function formatTimestamp(date) {
+  return date.toISOString().replace("T", " ").replace("Z", "");
+}
+const prettyConsoleSink = {
+  write: ({ scope, level, event, data, options }) => {
+    const timestamp = `${colors.gray}${formatTimestamp(options?.timestamp || /* @__PURE__ */ new Date())}${colors.reset}`;
+    const levelColor = level === "error" ? colors.red : level === "warn" ? colors.yellow : colors.blue;
+    const coloredScope = scope ? `${colors.cyan}[${scope}]${colors.reset}` : "";
+    const logPrefix = `${timestamp} ${levelColor}${level.toUpperCase()}${colors.reset} ${coloredScope} ${event}`;
+    if (level === "error" && data.error) {
+      const { error, ...otherData } = data;
+      console.error(logPrefix);
+      if (error.stack) {
+        console.error(`  ${error.stack}`);
+      } else if (error.type && error.message) {
+        console.error(`  ${error.type}: ${error.message}`);
+      }
+      if (Object.keys(otherData).length > 0) {
+        console.error(JSON.stringify(otherData, null, 2));
+      }
+    } else {
+      console[level](logPrefix);
+      if (Object.keys(data).length > 0) {
+        console[level](JSON.stringify(data, null, 2));
+      }
+    }
+  }
+};
+const jsonlConsoleSink = {
+  write: ({ id, scope, level, event, data, options }) => {
+    const timestamp = options?.timestamp || /* @__PURE__ */ new Date();
+    const logEntry = {
+      timestamp: timestamp.toISOString(),
+      id,
+      level,
+      scope: scope || void 0,
+      event,
+      data
+    };
+    console.log(JSON.stringify(logEntry));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createFileLogSink,
+  jsonlConsoleSink,
+  prettyConsoleSink
+});

package/dist/shared/logger/sinks.d.cts

@@ -0,0 +1,9 @@
+import { LoggerSink } from './logger.cjs';
+
+declare function createFileLogSink({ filePath, }: {
+    filePath: string;
+}): LoggerSink;
+declare const prettyConsoleSink: LoggerSink;
+declare const jsonlConsoleSink: LoggerSink;
+
+export { createFileLogSink, jsonlConsoleSink, prettyConsoleSink };

package/dist/shared/logger/sinks.d.ts

@@ -0,0 +1,9 @@
+import { LoggerSink } from './logger.js';
+
+declare function createFileLogSink({ filePath, }: {
+    filePath: string;
+}): LoggerSink;
+declare const prettyConsoleSink: LoggerSink;
+declare const jsonlConsoleSink: LoggerSink;
+
+export { createFileLogSink, jsonlConsoleSink, prettyConsoleSink };

package/dist/shared/logger/sinks.js

@@ -0,0 +1,124 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+function createFileLogSink({
+  filePath
+}) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const writeStream = fs.createWriteStream(filePath, { flags: "a" });
+  return {
+    write: ({ id, scope, level, event, data, options }) => {
+      if (writeStream.destroyed || writeStream.writableEnded) {
+        return;
+      }
+      const timestamp = options?.timestamp || /* @__PURE__ */ new Date();
+      const logEntry = {
+        timestamp: timestamp.toISOString(),
+        id,
+        level,
+        scope,
+        event,
+        data
+      };
+      const jsonLine = JSON.stringify(logEntry) + "\n";
+      try {
+        writeStream.write(jsonLine, (error) => {
+          if (error) {
+            console.error("Failed to write to log file:", error);
+            console[level]({ id, scope, event, data, timestamp });
+          }
+        });
+      } catch (error) {
+        console.error("Failed to write to log file:", error);
+        console[level]({ id, scope, event, data, timestamp });
+      }
+    },
+    flush: () => new Promise((resolve, reject) => {
+      if (!writeStream.writable || writeStream.writableEnded || writeStream.destroyed) {
+        resolve();
+        return;
+      }
+      writeStream.write("", (error) => {
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      });
+    }),
+    close: () => new Promise((resolve) => {
+      if (writeStream.destroyed || writeStream.closed) {
+        resolve();
+        return;
+      }
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      };
+      writeStream.once("finish", done);
+      writeStream.once("close", done);
+      writeStream.once("error", done);
+      try {
+        writeStream.end();
+      } catch {
+        done();
+      }
+    })
+  };
+}
+const colors = {
+  reset: "\x1B[0m",
+  gray: "\x1B[90m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m"
+};
+function formatTimestamp(date) {
+  return date.toISOString().replace("T", " ").replace("Z", "");
+}
+const prettyConsoleSink = {
+  write: ({ scope, level, event, data, options }) => {
+    const timestamp = `${colors.gray}${formatTimestamp(options?.timestamp || /* @__PURE__ */ new Date())}${colors.reset}`;
+    const levelColor = level === "error" ? colors.red : level === "warn" ? colors.yellow : colors.blue;
+    const coloredScope = scope ? `${colors.cyan}[${scope}]${colors.reset}` : "";
+    const logPrefix = `${timestamp} ${levelColor}${level.toUpperCase()}${colors.reset} ${coloredScope} ${event}`;
+    if (level === "error" && data.error) {
+      const { error, ...otherData } = data;
+      console.error(logPrefix);
+      if (error.stack) {
+        console.error(`  ${error.stack}`);
+      } else if (error.type && error.message) {
+        console.error(`  ${error.type}: ${error.message}`);
+      }
+      if (Object.keys(otherData).length > 0) {
+        console.error(JSON.stringify(otherData, null, 2));
+      }
+    } else {
+      console[level](logPrefix);
+      if (Object.keys(data).length > 0) {
+        console[level](JSON.stringify(data, null, 2));
+      }
+    }
+  }
+};
+const jsonlConsoleSink = {
+  write: ({ id, scope, level, event, data, options }) => {
+    const timestamp = options?.timestamp || /* @__PURE__ */ new Date();
+    const logEntry = {
+      timestamp: timestamp.toISOString(),
+      id,
+      level,
+      scope: scope || void 0,
+      event,
+      data
+    };
+    console.log(JSON.stringify(logEntry));
+  }
+};
+export {
+  createFileLogSink,
+  jsonlConsoleSink,
+  prettyConsoleSink
+};

package/dist/shared/paths/paths.cjs

@@ -0,0 +1,104 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var paths_exports = {};
+__export(paths_exports, {
+  ensureLibrettoPauseSignalDir: () => ensureLibrettoPauseSignalDir,
+  ensureLibrettoRunnerLogDir: () => ensureLibrettoRunnerLogDir,
+  ensureLibrettoSessionStatePath: () => ensureLibrettoSessionStatePath,
+  getLibrettoPauseSignalDir: () => getLibrettoPauseSignalDir,
+  getLibrettoPausedSignalPath: () => getLibrettoPausedSignalPath,
+  getLibrettoResumeSignalPath: () => getLibrettoResumeSignalPath,
+  getPauseSignalPathForDir: () => getPauseSignalPathForDir,
+  getRunnerLogPathForDir: () => getRunnerLogPathForDir
+});
+module.exports = __toCommonJS(paths_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+const LIBRETTO_DIRNAME = ".libretto";
+const LIBRETTO_SESSIONS_DIRNAME = "sessions";
+const SESSION_STATE_FILENAME = "state.json";
+const RUNNER_LOG_DIRNAME = "logs";
+const RUNNER_LOG_FILENAME = "logs.jsonl";
+const PAUSED_SIGNAL_SUFFIX = "paused";
+const RESUME_SIGNAL_SUFFIX = "resume";
+function getLibrettoRoot(cwd = process.cwd()) {
+  return (0, import_node_path.join)(cwd, LIBRETTO_DIRNAME);
+}
+function getLibrettoSessionsDir(cwd = process.cwd()) {
+  return (0, import_node_path.join)(getLibrettoRoot(cwd), LIBRETTO_SESSIONS_DIRNAME);
+}
+function getLibrettoSessionDir(sessionName, cwd = process.cwd()) {
+  return (0, import_node_path.join)(getLibrettoSessionsDir(cwd), sessionName);
+}
+function getLibrettoSessionStatePath(sessionName, cwd = process.cwd()) {
+  return (0, import_node_path.join)(getLibrettoSessionDir(sessionName, cwd), SESSION_STATE_FILENAME);
+}
+function getLibrettoPauseSignalDir(sessionName, cwd = process.cwd()) {
+  return getLibrettoSessionDir(sessionName, cwd);
+}
+function getLibrettoRunnerLogDir(sessionName, cwd = process.cwd()) {
+  return (0, import_node_path.join)(getLibrettoSessionDir(sessionName, cwd), RUNNER_LOG_DIRNAME);
+}
+function getRunnerLogPathForDir(logDir) {
+  return (0, import_node_path.join)(logDir, RUNNER_LOG_FILENAME);
+}
+function getPauseSignalPathForDir(signalDir, sessionName, signal) {
+  const suffix = signal === "paused" ? PAUSED_SIGNAL_SUFFIX : RESUME_SIGNAL_SUFFIX;
+  return (0, import_node_path.join)(signalDir, `${sessionName}.${suffix}`);
+}
+function getLibrettoPausedSignalPath(sessionName, cwd = process.cwd()) {
+  return getPauseSignalPathForDir(
+    getLibrettoPauseSignalDir(sessionName, cwd),
+    sessionName,
+    "paused"
+  );
+}
+function getLibrettoResumeSignalPath(sessionName, cwd = process.cwd()) {
+  return getPauseSignalPathForDir(
+    getLibrettoPauseSignalDir(sessionName, cwd),
+    sessionName,
+    "resume"
+  );
+}
+function ensureLibrettoSessionStatePath(sessionName, cwd = process.cwd()) {
+  const filePath = getLibrettoSessionStatePath(sessionName, cwd);
+  (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(filePath), { recursive: true });
+  return filePath;
+}
+function ensureLibrettoPauseSignalDir(sessionName, cwd = process.cwd()) {
+  const dir = getLibrettoPauseSignalDir(sessionName, cwd);
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  return dir;
+}
+function ensureLibrettoRunnerLogDir(sessionName, cwd = process.cwd()) {
+  const dir = getLibrettoRunnerLogDir(sessionName, cwd);
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  return dir;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ensureLibrettoPauseSignalDir,
+  ensureLibrettoRunnerLogDir,
+  ensureLibrettoSessionStatePath,
+  getLibrettoPauseSignalDir,
+  getLibrettoPausedSignalPath,
+  getLibrettoResumeSignalPath,
+  getPauseSignalPathForDir,
+  getRunnerLogPathForDir
+});

package/dist/shared/paths/paths.d.cts

@@ -0,0 +1,10 @@
+declare function getLibrettoPauseSignalDir(sessionName: string, cwd?: string): string;
+declare function getRunnerLogPathForDir(logDir: string): string;
+declare function getPauseSignalPathForDir(signalDir: string, sessionName: string, signal: "paused" | "resume"): string;
+declare function getLibrettoPausedSignalPath(sessionName: string, cwd?: string): string;
+declare function getLibrettoResumeSignalPath(sessionName: string, cwd?: string): string;
+declare function ensureLibrettoSessionStatePath(sessionName: string, cwd?: string): string;
+declare function ensureLibrettoPauseSignalDir(sessionName: string, cwd?: string): string;
+declare function ensureLibrettoRunnerLogDir(sessionName: string, cwd?: string): string;
+
+export { ensureLibrettoPauseSignalDir, ensureLibrettoRunnerLogDir, ensureLibrettoSessionStatePath, getLibrettoPauseSignalDir, getLibrettoPausedSignalPath, getLibrettoResumeSignalPath, getPauseSignalPathForDir, getRunnerLogPathForDir };

package/dist/shared/paths/paths.d.ts

@@ -0,0 +1,10 @@
+declare function getLibrettoPauseSignalDir(sessionName: string, cwd?: string): string;
+declare function getRunnerLogPathForDir(logDir: string): string;
+declare function getPauseSignalPathForDir(signalDir: string, sessionName: string, signal: "paused" | "resume"): string;
+declare function getLibrettoPausedSignalPath(sessionName: string, cwd?: string): string;
+declare function getLibrettoResumeSignalPath(sessionName: string, cwd?: string): string;
+declare function ensureLibrettoSessionStatePath(sessionName: string, cwd?: string): string;
+declare function ensureLibrettoPauseSignalDir(sessionName: string, cwd?: string): string;
+declare function ensureLibrettoRunnerLogDir(sessionName: string, cwd?: string): string;
+
+export { ensureLibrettoPauseSignalDir, ensureLibrettoRunnerLogDir, ensureLibrettoSessionStatePath, getLibrettoPauseSignalDir, getLibrettoPausedSignalPath, getLibrettoResumeSignalPath, getPauseSignalPathForDir, getRunnerLogPathForDir };

package/dist/shared/paths/paths.js

@@ -0,0 +1,73 @@
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+const LIBRETTO_DIRNAME = ".libretto";
+const LIBRETTO_SESSIONS_DIRNAME = "sessions";
+const SESSION_STATE_FILENAME = "state.json";
+const RUNNER_LOG_DIRNAME = "logs";
+const RUNNER_LOG_FILENAME = "logs.jsonl";
+const PAUSED_SIGNAL_SUFFIX = "paused";
+const RESUME_SIGNAL_SUFFIX = "resume";
+function getLibrettoRoot(cwd = process.cwd()) {
+  return join(cwd, LIBRETTO_DIRNAME);
+}
+function getLibrettoSessionsDir(cwd = process.cwd()) {
+  return join(getLibrettoRoot(cwd), LIBRETTO_SESSIONS_DIRNAME);
+}
+function getLibrettoSessionDir(sessionName, cwd = process.cwd()) {
+  return join(getLibrettoSessionsDir(cwd), sessionName);
+}
+function getLibrettoSessionStatePath(sessionName, cwd = process.cwd()) {
+  return join(getLibrettoSessionDir(sessionName, cwd), SESSION_STATE_FILENAME);
+}
+function getLibrettoPauseSignalDir(sessionName, cwd = process.cwd()) {
+  return getLibrettoSessionDir(sessionName, cwd);
+}
+function getLibrettoRunnerLogDir(sessionName, cwd = process.cwd()) {
+  return join(getLibrettoSessionDir(sessionName, cwd), RUNNER_LOG_DIRNAME);
+}
+function getRunnerLogPathForDir(logDir) {
+  return join(logDir, RUNNER_LOG_FILENAME);
+}
+function getPauseSignalPathForDir(signalDir, sessionName, signal) {
+  const suffix = signal === "paused" ? PAUSED_SIGNAL_SUFFIX : RESUME_SIGNAL_SUFFIX;
+  return join(signalDir, `${sessionName}.${suffix}`);
+}
+function getLibrettoPausedSignalPath(sessionName, cwd = process.cwd()) {
+  return getPauseSignalPathForDir(
+    getLibrettoPauseSignalDir(sessionName, cwd),
+    sessionName,
+    "paused"
+  );
+}
+function getLibrettoResumeSignalPath(sessionName, cwd = process.cwd()) {
+  return getPauseSignalPathForDir(
+    getLibrettoPauseSignalDir(sessionName, cwd),
+    sessionName,
+    "resume"
+  );
+}
+function ensureLibrettoSessionStatePath(sessionName, cwd = process.cwd()) {
+  const filePath = getLibrettoSessionStatePath(sessionName, cwd);
+  mkdirSync(dirname(filePath), { recursive: true });
+  return filePath;
+}
+function ensureLibrettoPauseSignalDir(sessionName, cwd = process.cwd()) {
+  const dir = getLibrettoPauseSignalDir(sessionName, cwd);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function ensureLibrettoRunnerLogDir(sessionName, cwd = process.cwd()) {
+  const dir = getLibrettoRunnerLogDir(sessionName, cwd);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+export {
+  ensureLibrettoPauseSignalDir,
+  ensureLibrettoRunnerLogDir,
+  ensureLibrettoSessionStatePath,
+  getLibrettoPauseSignalDir,
+  getLibrettoPausedSignalPath,
+  getLibrettoResumeSignalPath,
+  getPauseSignalPathForDir,
+  getRunnerLogPathForDir
+};