@nmakarov/cli-toolkit 0.14.2 → 0.18.0

package/dist/cli-runner.js

@@ -0,0 +1,4989 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/screen/components.ts
+import { createElement as h } from "react";
+import { Box, Text } from "ink";
+function getScreenWidth(maxWidth = null) {
+  const terminalWidth = process.stdout.columns || 80;
+  const availableWidth = Math.max(20, terminalWidth - 4);
+  return maxWidth ? Math.min(availableWidth, maxWidth) : availableWidth;
+}
+function ScreenContainer({ children }) {
+  const width = getScreenWidth();
+  return h(Box, {
+    flexDirection: "column",
+    marginTop: 1,
+    borderStyle: "single",
+    borderColor: "cyan",
+    paddingX: 1,
+    width
+    // Use the calculated width directly
+  }, children);
+}
+function ScreenRow({ children }) {
+  return h(Box, { flexDirection: "column" }, children);
+}
+function ScreenTitle({ text }) {
+  return h(
+    ScreenRow,
+    {},
+    h(Text, { bold: true, color: "cyan" }, text)
+  );
+}
+function ScreenDivider({ width }) {
+  const dividerWidth = width || getScreenWidth() - 4;
+  return h(Text, { color: "cyan", dimColor: true }, "\u2500".repeat(dividerWidth));
+}
+function ScreenBody({ children, alignItems = "flex-start" }) {
+  return h(Box, { flexDirection: "column", alignItems }, children);
+}
+function ScreenFooter({ lines, textStyle }) {
+  const defaultTextStyle = {
+    dimColor: true,
+    color: "white"
+  };
+  const finalTextStyle = { ...defaultTextStyle, ...textStyle };
+  const flattenAndWrap = (items, keyPrefix = "") => {
+    const result = [];
+    let keyIndex = 0;
+    items.forEach((item, index) => {
+      if (Array.isArray(item)) {
+        const nested = flattenAndWrap(item, `${keyPrefix}-${index}`);
+        result.push(...nested);
+      } else if (typeof item === "string") {
+        result.push(
+          h(Text, { key: `${keyPrefix}-${keyIndex++}`, ...finalTextStyle }, item)
+        );
+      } else {
+        const element = item;
+        if (element.key === null || element.key === void 0) {
+          result.push(
+            h(Text, { key: `${keyPrefix}-${keyIndex++}`, ...finalTextStyle }, element)
+          );
+        } else {
+          result.push(element);
+        }
+      }
+    });
+    return result;
+  };
+  const wrappedItems = flattenAndWrap(lines);
+  return h(
+    Box,
+    { flexDirection: "column" },
+    h(Box, { flexDirection: "row" }, ...wrappedItems)
+  );
+}
+var init_components = __esm({
+  "src/screen/components.ts"() {
+    "use strict";
+  }
+});
+
+// src/screen/list-components.ts
+import React2, { useState, useEffect, useRef, createElement } from "react";
+import { Box as Box2, Text as Text2 } from "ink";
+function MultiColumnListComponent({ items, ctx, selectedIndexRef }) {
+  const [, forceUpdate] = useState({});
+  const termWidth = (process.stdout.columns || 80) - 8;
+  const maxItemLength = Math.max(...items.map((w) => w.length));
+  const columnWidth = maxItemLength + 3;
+  const columns = Math.max(1, Math.floor(termWidth / columnWidth));
+  const itemsPerColumn = Math.ceil(items.length / columns);
+  useEffect(() => {
+    ctx.setAction("moveUp", () => {
+      selectedIndexRef.current = Math.max(0, selectedIndexRef.current - 1);
+      forceUpdate({});
+    });
+    ctx.setAction("moveDown", () => {
+      selectedIndexRef.current = Math.min(items.length - 1, selectedIndexRef.current + 1);
+      forceUpdate({});
+    });
+    ctx.setAction("moveLeft", () => {
+      if (selectedIndexRef.current === 0) {
+        ctx.goBack();
+      } else {
+        selectedIndexRef.current = Math.max(0, selectedIndexRef.current - itemsPerColumn);
+        forceUpdate({});
+      }
+    });
+    ctx.setAction("moveRight", () => {
+      selectedIndexRef.current = Math.min(items.length - 1, selectedIndexRef.current + itemsPerColumn);
+      forceUpdate({});
+    });
+    ctx.setKeyBinding([
+      { key: "leftArrow", caption: "navigate", action: "moveLeft", order: 0 },
+      { key: "rightArrow", caption: "navigate", action: "moveRight", order: 0 },
+      { key: "upArrow", caption: "navigate", action: "moveUp", order: 0 },
+      { key: "downArrow", caption: "navigate", action: "moveDown", order: 0 }
+    ]);
+    ctx.addFooter(`Total: ${items.length} items`);
+  }, []);
+  const selectedIndex = selectedIndexRef.current;
+  const rows = [];
+  for (let row = 0; row < itemsPerColumn; row++) {
+    const cols = [];
+    for (let col = 0; col < columns; col++) {
+      const index = col * itemsPerColumn + row;
+      if (index < items.length) {
+        const isSelected = index === selectedIndex;
+        cols.push(
+          h2(
+            Box2,
+            { key: index, width: columnWidth },
+            h2(Text2, {
+              color: isSelected ? "black" : "white",
+              backgroundColor: isSelected ? "cyan" : void 0,
+              bold: isSelected
+            }, items[index].padEnd(maxItemLength))
+          )
+        );
+      }
+    }
+    rows.push(
+      h2(ScreenRow, { key: row, children: h2(Box2, { flexDirection: "row" }, ...cols) })
+    );
+  }
+  return h2(Box2, { flexDirection: "column" }, ...rows);
+}
+function MultiColumnListWithPreviewComponent({
+  items,
+  getPreviewContent,
+  ctx,
+  selectedIndexRef
+}) {
+  const [, forceUpdate] = useState({});
+  const termWidth = (process.stdout.columns || 80) - 8;
+  const maxItemLength = Math.max(...items.map((w) => w.length));
+  const columnWidth = maxItemLength + 3;
+  const columns = Math.max(1, Math.floor(termWidth / columnWidth));
+  const itemsPerColumn = Math.ceil(items.length / columns);
+  useEffect(() => {
+    ctx.setAction("moveUp", () => {
+      selectedIndexRef.current = Math.max(0, selectedIndexRef.current - 1);
+      forceUpdate({});
+    });
+    ctx.setAction("moveDown", () => {
+      selectedIndexRef.current = Math.min(items.length - 1, selectedIndexRef.current + 1);
+      forceUpdate({});
+    });
+    ctx.setAction("moveLeft", () => {
+      if (selectedIndexRef.current === 0) {
+        ctx.goBack();
+      } else {
+        selectedIndexRef.current = Math.max(0, selectedIndexRef.current - itemsPerColumn);
+        forceUpdate({});
+      }
+    });
+    ctx.setAction("moveRight", () => {
+      selectedIndexRef.current = Math.min(items.length - 1, selectedIndexRef.current + itemsPerColumn);
+      forceUpdate({});
+    });
+    ctx.setKeyBinding([
+      { key: "leftArrow", caption: "navigate", action: "moveLeft", order: 0 },
+      { key: "rightArrow", caption: "navigate", action: "moveRight", order: 0 },
+      { key: "upArrow", caption: "navigate", action: "moveUp", order: 0 },
+      { key: "downArrow", caption: "navigate", action: "moveDown", order: 0 }
+    ]);
+    ctx.addFooter(`Total: ${items.length} items`);
+  }, []);
+  const selectedIndex = selectedIndexRef.current;
+  const selectedItem = items[selectedIndex];
+  const rows = [];
+  for (let row = 0; row < itemsPerColumn; row++) {
+    const cols = [];
+    for (let col = 0; col < columns; col++) {
+      const index = col * itemsPerColumn + row;
+      if (index < items.length) {
+        const isSelected = index === selectedIndex;
+        cols.push(
+          h2(
+            Box2,
+            { key: index, width: columnWidth },
+            h2(Text2, {
+              color: isSelected ? "black" : "white",
+              backgroundColor: isSelected ? "cyan" : void 0,
+              bold: isSelected
+            }, items[index].padEnd(maxItemLength))
+          )
+        );
+      }
+    }
+    rows.push(
+      h2(ScreenRow, { key: row, children: h2(Box2, { flexDirection: "row" }, ...cols) })
+    );
+  }
+  const previewContent = getPreviewContent ? getPreviewContent(selectedItem) : selectedItem;
+  const previewRows = [];
+  if (typeof previewContent === "string") {
+    previewRows.push(h2(ScreenRow, { key: "preview-string", children: h2(Text2, { bold: true }, previewContent) }));
+  } else if (typeof previewContent === "object" && !React2.isValidElement(previewContent) && previewContent !== null) {
+    Object.entries(previewContent).forEach(([key, value], idx) => {
+      previewRows.push(h2(ScreenRow, { key: `preview-${key}-${idx}`, children: h2(Text2, {}, `${key}: ${value}`) }));
+    });
+  } else if (React2.isValidElement(previewContent)) {
+    previewRows.push(h2(ScreenRow, { key: "preview-element", children: previewContent }));
+  }
+  return h2(
+    Box2,
+    { flexDirection: "column" },
+    ...rows,
+    h2(ScreenRow, { key: "spacer-1", children: h2(Text2, {}, " ") }),
+    h2(ScreenDivider, { key: "divider" }),
+    h2(ScreenRow, { key: "spacer-2", children: h2(Text2, {}, " ") }),
+    ...previewRows
+  );
+}
+function ListComponent({ items, ctx, selectedIndexRef, renderItem, getTitle, sortable = false, maxHeight, sortHighlightStyle, selectionMarker = " " }) {
+  const [, forceUpdate] = useState({});
+  const [sortOrder, setSortOrder] = useState("none");
+  const [scrollOffset, setScrollOffset] = useState(0);
+  const scrollStateRef = useRef({ scrollOffset: 0, maxHeight: 0, totalItems: 0 });
+  const defaultGetTitle = (item) => {
+    return getTitle ? getTitle(item) : typeof item.value === "string" ? item.value : item.value?.title || item.name;
+  };
+  const titleGetter = getTitle || defaultGetTitle;
+  const displayItems = sortable && sortOrder !== "none" ? [...items].sort((a, b) => {
+    const titleA = titleGetter(a).toLowerCase();
+    const titleB = titleGetter(b).toLowerCase();
+    if (sortOrder === "asc") {
+      return titleA < titleB ? -1 : titleA > titleB ? 1 : 0;
+    } else {
+      return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
+    }
+  }) : items;
+  const effectiveMaxHeight = maxHeight || displayItems.length;
+  const canScroll = displayItems.length > effectiveMaxHeight;
+  const maxScrollOffset = Math.max(0, displayItems.length - effectiveMaxHeight);
+  const clampedScrollOffset = Math.min(Math.max(0, scrollOffset), maxScrollOffset);
+  const visibleItems = displayItems.slice(clampedScrollOffset, clampedScrollOffset + effectiveMaxHeight);
+  const canScrollUp = clampedScrollOffset > 0;
+  const canScrollDown = clampedScrollOffset < maxScrollOffset;
+  scrollStateRef.current = { scrollOffset, maxHeight: effectiveMaxHeight, totalItems: displayItems.length };
+  useEffect(() => {
+    ctx.setAction("moveUp", () => {
+      const newIndex = Math.max(0, selectedIndexRef.current - 1);
+      selectedIndexRef.current = newIndex;
+      const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
+      const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
+      const currentClampedScrollOffset = Math.min(Math.max(0, currentScrollOffset), currentMaxScrollOffset);
+      if (newIndex < currentClampedScrollOffset) {
+        setScrollOffset(newIndex);
+      }
+      forceUpdate({});
+    });
+    ctx.setAction("moveDown", () => {
+      const currentItems = sortable && sortOrder !== "none" ? [...items].sort((a, b) => {
+        const titleA = titleGetter(a).toLowerCase();
+        const titleB = titleGetter(b).toLowerCase();
+        if (sortOrder === "asc") {
+          return titleA < titleB ? -1 : titleA > titleB ? 1 : 0;
+        } else {
+          return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
+        }
+      }) : items;
+      const maxIndex = currentItems.length - 1;
+      const newIndex = Math.min(maxIndex, selectedIndexRef.current + 1);
+      selectedIndexRef.current = newIndex;
+      const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
+      const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
+      const currentClampedScrollOffset = Math.min(Math.max(0, currentScrollOffset), currentMaxScrollOffset);
+      if (newIndex >= currentClampedScrollOffset + currentMaxHeight) {
+        setScrollOffset(newIndex - currentMaxHeight + 1);
+      }
+      forceUpdate({});
+    });
+    ctx.setAction("scrollUp", () => {
+      const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
+      const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
+      const newScrollOffset = Math.max(0, currentScrollOffset - 1);
+      setScrollOffset(newScrollOffset);
+      forceUpdate({});
+    });
+    ctx.setAction("scrollDown", () => {
+      const { scrollOffset: currentScrollOffset, maxHeight: currentMaxHeight, totalItems } = scrollStateRef.current;
+      const currentMaxScrollOffset = Math.max(0, totalItems - currentMaxHeight);
+      const newScrollOffset = Math.min(currentMaxScrollOffset, currentScrollOffset + 1);
+      setScrollOffset(newScrollOffset);
+      forceUpdate({});
+    });
+    if (sortable) {
+      ctx.setAction("toggleSort", () => {
+        const nextSort = sortOrder === "none" ? "asc" : sortOrder === "asc" ? "desc" : "none";
+        const currentSelectedItem = displayItems[selectedIndexRef.current];
+        setSortOrder(nextSort);
+        const newSortedItems = nextSort !== "none" ? [...items].sort((a, b) => {
+          const titleA = titleGetter(a).toLowerCase();
+          const titleB = titleGetter(b).toLowerCase();
+          if (nextSort === "asc") {
+            return titleA < titleB ? -1 : titleA > titleB ? 1 : 0;
+          } else {
+            return titleA > titleB ? -1 : titleA < titleB ? 1 : 0;
+          }
+        }) : items;
+        const newIndex = newSortedItems.findIndex((item) => item === currentSelectedItem);
+        if (newIndex !== -1) {
+          selectedIndexRef.current = newIndex;
+          setScrollOffset(newIndex);
+        } else {
+          selectedIndexRef.current = 0;
+          setScrollOffset(0);
+        }
+        forceUpdate({});
+      });
+      const defaultHighlightStyle = {
+        color: "black",
+        backgroundColor: "green",
+        bold: true
+      };
+      const highlightStyle = { ...defaultHighlightStyle, ...sortHighlightStyle };
+      const sortCaption = () => {
+        if (sortOrder === "none") {
+          return h2(Text2, {}, "s to toggle sort");
+        } else {
+          const sortLabel = sortOrder === "asc" ? "ASC" : "DESC";
+          return h2(
+            Text2,
+            {},
+            "s to toggle ",
+            h2(Text2, { color: "white", bold: true }, "sort"),
+            " ",
+            h2(Text2, highlightStyle, ` ${sortLabel} `)
+          );
+        }
+      };
+      ctx.setKeyBinding([
+        { key: "upArrow", caption: "navigate", action: "moveUp", order: 0 },
+        { key: "downArrow", caption: "navigate", action: "moveDown", order: 0 },
+        {
+          key: "s",
+          caption: sortCaption,
+          action: "toggleSort",
+          order: 5
+        }
+      ]);
+      ctx.update();
+    } else {
+      ctx.setKeyBinding([
+        { key: "upArrow", caption: "navigate", action: "moveUp", order: 0 },
+        { key: "downArrow", caption: "navigate", action: "moveDown", order: 0 }
+      ]);
+    }
+  }, [sortOrder, sortable]);
+  const selectedIndex = selectedIndexRef.current;
+  const defaultRenderItem = (item, isSelected, displayIndex, actualIndex) => {
+    const isFirstVisible = displayIndex === 0;
+    const isLastVisible = displayIndex === visibleItems.length - 1;
+    let arrowPrefix = "";
+    let selectionPrefix = "";
+    if (isFirstVisible && canScrollUp) {
+      arrowPrefix = "\u2191 ";
+    } else if (isLastVisible && canScrollDown) {
+      arrowPrefix = "\u2193 ";
+    } else {
+      arrowPrefix = "  ";
+    }
+    if (isSelected) {
+      selectionPrefix = selectionMarker;
+    } else {
+      selectionPrefix = " ".repeat(selectionMarker.length);
+    }
+    return h2(
+      Box2,
+      { flexDirection: "row" },
+      // Arrow (clickable if functional, not highlighted)
+      h2(Text2, {
+        key: `arrow-${actualIndex}`,
+        color: "white"
+      }, arrowPrefix),
+      // Selection marker space (always same width, not highlighted) 
+      h2(Text2, { key: `marker-${actualIndex}`, color: "white" }, selectionPrefix),
+      // Item name (highlighted if selected)
+      h2(Text2, {
+        key: `name-${actualIndex}`,
+        color: isSelected ? "black" : "white",
+        backgroundColor: isSelected ? "cyan" : void 0,
+        bold: isSelected
+      }, item.name)
+    );
+  };
+  const itemRenderer = renderItem || defaultRenderItem;
+  return h2(
+    Box2,
+    { flexDirection: "column" },
+    ...visibleItems.map((item, displayIndex) => {
+      const actualIndex = clampedScrollOffset + displayIndex;
+      const isSelected = actualIndex === selectedIndex;
+      if (renderItem) {
+        const isFirstVisible = displayIndex === 0;
+        const isLastVisible = displayIndex === visibleItems.length - 1;
+        let arrowPrefix = "";
+        let selectionPrefix = "";
+        if (isFirstVisible && canScrollUp) {
+          arrowPrefix = "\u2191 ";
+        } else if (isLastVisible && canScrollDown) {
+          arrowPrefix = "\u2193 ";
+        } else {
+          arrowPrefix = "  ";
+        }
+        if (isSelected) {
+          selectionPrefix = selectionMarker;
+        } else {
+          selectionPrefix = " ".repeat(selectionMarker.length);
+        }
+        return h2(ScreenRow, {
+          key: `item-${actualIndex}`,
+          children: h2(
+            Box2,
+            { flexDirection: "row" },
+            // Arrow (clickable if functional, not highlighted)
+            h2(Text2, {
+              key: `arrow-${actualIndex}`,
+              color: "white"
+            }, arrowPrefix),
+            // Selection marker space (always same width, not highlighted) 
+            h2(Text2, { key: `marker-${actualIndex}`, color: "white" }, selectionPrefix),
+            // Custom rendered content
+            renderItem(item, isSelected, displayIndex)
+          )
+        });
+      } else {
+        return h2(ScreenRow, {
+          key: `item-${actualIndex}`,
+          children: itemRenderer(item, isSelected, displayIndex, actualIndex)
+        });
+      }
+    })
+  );
+}
+var h2;
+var init_list_components = __esm({
+  "src/screen/list-components.ts"() {
+    "use strict";
+    init_components();
+    h2 = createElement;
+  }
+});
+
+// src/screen/screens.ts
+import { useState as useState2, createElement as h3 } from "react";
+import { render, useInput, Text as Text3 } from "ink";
+function groupKeyBindings(bindings) {
+  const groups = {};
+  const enabledBindings = bindings.filter((b) => b.enabled !== false);
+  enabledBindings.forEach((binding) => {
+    const caption = typeof binding.caption === "string" ? binding.caption : "";
+    if (!groups[caption]) {
+      groups[caption] = {
+        keys: [],
+        caption,
+        order: binding.order || 999
+      };
+    }
+    groups[caption].keys.push(binding.key);
+  });
+  return Object.values(groups);
+}
+function formatKeyBindings(bindings, mode = "long") {
+  const resolvedBindings = bindings.map((binding) => {
+    let resolvedCaption = binding.caption;
+    if (typeof binding.caption === "function") {
+      resolvedCaption = binding.caption();
+    }
+    return {
+      ...binding,
+      resolvedCaption
+    };
+  });
+  const groups = groupKeyBindings(resolvedBindings.map((b) => ({
+    ...b,
+    caption: typeof b.resolvedCaption === "string" ? b.resolvedCaption : ""
+  })));
+  groups.sort((a, b) => a.order - b.order);
+  const items = [];
+  groups.forEach((group) => {
+    const bindingWithCustom = resolvedBindings.find(
+      (b) => group.keys.includes(b.key) && typeof b.resolvedCaption !== "string"
+    );
+    if (bindingWithCustom && bindingWithCustom.resolvedCaption) {
+      items.push(bindingWithCustom.resolvedCaption);
+    } else {
+      const keyStr = formatKeys(group.keys);
+      if (mode === "long") {
+        items.push(`${keyStr} to ${group.caption}`);
+      } else {
+        items.push(keyStr);
+      }
+    }
+  });
+  return items;
+}
+function formatKeys(keys) {
+  const keyMap = {
+    "escape": "esc",
+    "leftArrow": "\u2190",
+    "rightArrow": "\u2192",
+    "upArrow": "\u2191",
+    "downArrow": "\u2193",
+    "return": "enter"
+  };
+  return keys.map((k) => keyMap[k] || k).join("/");
+}
+async function showScreen(config2) {
+  const {
+    title,
+    onRender,
+    parentData = {}
+  } = config2;
+  return new Promise((resolve2) => {
+    let instance;
+    const keyBindings = [];
+    const actions = {};
+    const customFooterItems = [];
+    let renderResult = null;
+    let initialized = false;
+    const Screen = () => {
+      const [updateCounter, setUpdateCounter] = useState2(0);
+      if (!initialized) {
+        const defaultBindings = [
+          { key: "escape", caption: "go back", action: "back", protected: true, order: 1 },
+          { key: "leftArrow", caption: "go back", action: "back", protected: false, order: 1 }
+          // Note: 'select' is not a default - components add it if needed
+        ];
+        defaultBindings.forEach((binding) => {
+          keyBindings.push(binding);
+        });
+        actions.back = () => {
+          cleanup(null);
+        };
+        initialized = true;
+      }
+      const context = {
+        setAction: (actionName, handlerFn) => {
+          actions[actionName] = handlerFn;
+        },
+        setKeyBinding: (bindingOrBindings) => {
+          const bindingsToSet = Array.isArray(bindingOrBindings) ? bindingOrBindings : [bindingOrBindings];
+          bindingsToSet.forEach((binding) => {
+            const existingIndex = keyBindings.findIndex((b) => b.key === binding.key);
+            if (existingIndex >= 0) {
+              const existing = keyBindings[existingIndex];
+              if (existing.protected) {
+                console.warn(`Cannot override protected key: ${binding.key}`);
+                return;
+              }
+              keyBindings[existingIndex] = {
+                ...existing,
+                ...binding,
+                order: binding.order !== void 0 ? binding.order : existing.order,
+                enabled: binding.enabled !== void 0 ? binding.enabled : existing.enabled !== void 0 ? existing.enabled : true
+              };
+            } else {
+              keyBindings.push({
+                protected: false,
+                order: 999,
+                enabled: true,
+                ...binding
+              });
+            }
+          });
+        },
+        updateKeyBinding: (keyName, updates) => {
+          const index = keyBindings.findIndex((b) => b.key === keyName);
+          if (index >= 0) {
+            keyBindings[index] = {
+              ...keyBindings[index],
+              ...updates
+            };
+          }
+        },
+        removeKeyBinding: (keyName) => {
+          const index = keyBindings.findIndex((b) => b.key === keyName);
+          if (index >= 0) {
+            if (keyBindings[index].protected) {
+              console.warn(`Cannot remove protected key: ${keyName}`);
+              return;
+            }
+            keyBindings.splice(index, 1);
+          }
+        },
+        addFooter: (item) => {
+          customFooterItems.push(item);
+        },
+        clearFooter: () => {
+          customFooterItems.length = 0;
+        },
+        setFooter: (items) => {
+          customFooterItems.length = 0;
+          const itemsArray = Array.isArray(items) ? items : [items];
+          customFooterItems.push(...itemsArray);
+        },
+        update: () => {
+          setUpdateCounter((c) => c + 1);
+        },
+        goBack: () => {
+          if (actions.back) {
+            actions.back();
+          }
+        },
+        close: (result) => {
+          cleanup(result);
+        },
+        parentData
+      };
+      if (!renderResult) {
+        renderResult = onRender(context);
+      }
+      useInput((input, key) => {
+        if (key.ctrl && input === "c") {
+          cleanup(null);
+          process.exit(0);
+          return;
+        }
+        let matchedBinding = null;
+        for (const binding of keyBindings) {
+          let keyMatches = false;
+          if (key[binding.key]) {
+            keyMatches = true;
+          } else if (input === binding.key) {
+            keyMatches = true;
+          } else if (key?.name === binding.key) {
+            keyMatches = true;
+          }
+          if (keyMatches) {
+            if (binding.enabled === false) {
+              continue;
+            }
+            if (binding.condition && !binding.condition(context)) {
+              continue;
+            }
+            matchedBinding = binding;
+            break;
+          }
+        }
+        if (matchedBinding && actions[matchedBinding.action]) {
+          const actionResult = actions[matchedBinding.action]({
+            input,
+            key,
+            binding: matchedBinding
+          });
+        }
+      });
+      const footerLines = [];
+      const bindingItems = formatKeyBindings(keyBindings, "long");
+      if (bindingItems.length > 0) {
+        const bindingsLine = [];
+        bindingItems.forEach((item, idx) => {
+          if (idx > 0) {
+            bindingsLine.push(", ");
+          }
+          bindingsLine.push(item);
+        });
+        const allStrings = bindingItems.every((item) => typeof item === "string");
+        if (allStrings) {
+          footerLines.push(bindingsLine.join(""));
+        } else {
+          const wrappedBindingsLine = bindingsLine.map(
+            (item) => typeof item === "string" ? h3(Text3, {}, item) : item
+          );
+          footerLines.push(wrappedBindingsLine);
+        }
+      }
+      customFooterItems.forEach((item) => {
+        if (typeof item === "string") {
+          footerLines.push(item);
+        } else {
+          footerLines.push(item);
+        }
+      });
+      return h3(
+        ScreenContainer,
+        {},
+        h3(ScreenTitle, { text: title }),
+        h3(ScreenDivider),
+        h3(ScreenRow, {}, h3(Text3, {}, " ")),
+        renderResult,
+        h3(ScreenRow, {}, h3(Text3, {}, " ")),
+        h3(ScreenDivider),
+        h3(ScreenFooter, { lines: footerLines })
+      );
+    };
+    const cleanup = (result) => {
+      if (instance) instance.unmount();
+      setTimeout(() => resolve2(result), 50);
+    };
+    instance = render(h3(Screen));
+  });
+}
+async function showListScreen(config2) {
+  const { title, items, onSelect, onEscape, parentData, initialSelectedIndex = 0, renderItem, getTitle, sortable, maxHeight, sortHighlightStyle, selectionMarker } = config2;
+  return showScreen({
+    title,
+    parentData,
+    onRender: (ctx) => {
+      const selectedIndexRef = { current: initialSelectedIndex };
+      ctx.setAction("select", () => {
+        const selected = items[selectedIndexRef.current];
+        if (onSelect) {
+          const result = onSelect(selected.value, selectedIndexRef.current);
+          ctx.close(result);
+        }
+      });
+      if (onEscape) {
+        ctx.setAction("back", () => {
+          const result = onEscape(selectedIndexRef.current);
+          ctx.close(result);
+        });
+      }
+      ctx.setKeyBinding({ key: "return", caption: "select", action: "select", order: 2 });
+      return h3(ListComponent, { items, ctx, selectedIndexRef, renderItem, getTitle, sortable, maxHeight, sortHighlightStyle, selectionMarker });
+    }
+  });
+}
+async function showMultiColumnListScreen(config2) {
+  const { title, items, onSelect, onEscape, parentData, initialSelectedIndex = 0 } = config2;
+  return showScreen({
+    title,
+    parentData,
+    onRender: (ctx) => {
+      const selectedIndexRef = { current: initialSelectedIndex };
+      ctx.setAction("select", () => {
+        const selected = items[selectedIndexRef.current];
+        if (onSelect) {
+          const result = onSelect(selected, selectedIndexRef.current);
+          ctx.close(result);
+        }
+      });
+      if (onEscape) {
+        ctx.setAction("back", () => {
+          const result = onEscape(selectedIndexRef.current);
+          ctx.close(result);
+        });
+      }
+      ctx.setKeyBinding({ key: "return", caption: "select", action: "select", order: 2 });
+      return h3(MultiColumnListComponent, { items, ctx, selectedIndexRef });
+    }
+  });
+}
+async function showMultiColumnListWithPreviewScreen(config2) {
+  const { title, items, getPreviewContent, onSelect, onEscape, parentData, initialSelectedIndex = 0 } = config2;
+  return showScreen({
+    title,
+    parentData,
+    onRender: (ctx) => {
+      const selectedIndexRef = { current: initialSelectedIndex };
+      ctx.setAction("select", () => {
+        const selected = items[selectedIndexRef.current];
+        if (onSelect) {
+          const result = onSelect(selected, selectedIndexRef.current);
+          ctx.close(result);
+        }
+      });
+      if (onEscape) {
+        ctx.setAction("back", () => {
+          const result = onEscape(selectedIndexRef.current);
+          ctx.close(result);
+        });
+      }
+      ctx.setKeyBinding({ key: "return", caption: "select", action: "select", order: 2 });
+      return h3(MultiColumnListWithPreviewComponent, { items, getPreviewContent, ctx, selectedIndexRef });
+    }
+  });
+}
+var showMenuScreen, showWordGridScreen;
+var init_screens = __esm({
+  "src/screen/screens.ts"() {
+    "use strict";
+    init_components();
+    init_list_components();
+    showMenuScreen = showListScreen;
+    showWordGridScreen = showMultiColumnListScreen;
+  }
+});
+
+// src/screen/ui-elements.ts
+import { createElement as h4 } from "react";
+import { Box as Box4, Text as Text4 } from "ink";
+function ListItem({
+  children,
+  isSelected = false,
+  color = "white",
+  backgroundColor,
+  bold = false,
+  dimColor = false
+}) {
+  return h4(
+    Box4,
+    {},
+    h4(Text4, {
+      color: isSelected ? backgroundColor || "green" : color,
+      backgroundColor: isSelected ? color : backgroundColor,
+      bold: isSelected || bold,
+      dimColor: !isSelected && dimColor
+    }, children)
+  );
+}
+function TextBlock({
+  text,
+  color = "white",
+  dimmed = false,
+  bold = false,
+  maxWidth
+}) {
+  return h4(
+    Box4,
+    {},
+    h4(Text4, {
+      color,
+      dimColor: dimmed,
+      bold
+    }, text)
+  );
+}
+function Divider({ character = "\u2500", width = 80 }) {
+  return h4(
+    Box4,
+    { marginY: 1 },
+    h4(Text4, { dimColor: true }, character.repeat(width))
+  );
+}
+function GridCell({
+  children,
+  width,
+  color = "white",
+  backgroundColor,
+  bold = false,
+  dimColor = false,
+  align = "left"
+}) {
+  return h4(
+    Box4,
+    { width },
+    h4(Text4, {
+      color,
+      backgroundColor,
+      bold,
+      dimColor,
+      textAlign: align
+    }, children)
+  );
+}
+function InputField({ prompt, value, onChange, onSubmit }) {
+  return h4(
+    Box4,
+    { flexDirection: "column" },
+    h4(Text4, {}, prompt),
+    h4(
+      Box4,
+      { marginTop: 1 },
+      h4(Text4, { color: "cyan" }, " > ", value, "_")
+    )
+  );
+}
+var init_ui_elements = __esm({
+  "src/screen/ui-elements.ts"() {
+    "use strict";
+  }
+});
+
+// src/screen/utils.ts
+function buildBreadcrumb(parts) {
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0];
+  return parts.slice(1).map((part) => `\u2190  ${part}`).join("  ");
+}
+function buildDetailBreadcrumb(path5, suffix = "") {
+  if (path5.length <= 1) {
+    return suffix ? `\u2190  ${suffix}` : path5[0] || "";
+  }
+  const breadcrumb = buildBreadcrumb(path5);
+  return suffix ? `${breadcrumb} ${suffix}` : breadcrumb;
+}
+var init_utils = __esm({
+  "src/screen/utils.ts"() {
+    "use strict";
+  }
+});
+
+// src/screen/footer-builder.ts
+function buildFooter(config2 = {}) {
+  const {
+    navigation = null,
+    actions = null,
+    info = null,
+    escape = "Esc to go back",
+    custom = null
+  } = config2;
+  const lines = [];
+  const mainParts = [];
+  if (navigation) {
+    mainParts.push(navigation);
+  }
+  if (actions) {
+    mainParts.push(actions);
+  }
+  if (escape) {
+    mainParts.push(escape);
+  }
+  if (mainParts.length > 0) {
+    lines.push(mainParts.join(", "));
+  }
+  if (info) {
+    const infoLines = Array.isArray(info) ? info : [info];
+    lines.push(...infoLines);
+  }
+  if (custom) {
+    const customLines = Array.isArray(custom) ? custom : [custom];
+    lines.push(...customLines);
+  }
+  return lines;
+}
+function organizeFooterMessages(messages) {
+  if (!messages || messages.length === 0) {
+    return ["Esc to go back"];
+  }
+  const navigation = messages.filter((m) => m.includes("\u2191") || m.includes("\u2193") || m.includes("\u2190") || m.includes("\u2192"));
+  const actions = messages.filter((m) => m.includes("Enter") || m.includes("select") || m.includes("submit"));
+  const escape = messages.filter((m) => m.includes("Esc"));
+  const others = messages.filter(
+    (m) => !navigation.includes(m) && !actions.includes(m) && !escape.includes(m)
+  );
+  const lines = [];
+  const mainLine = [...navigation, ...actions, ...escape].join(", ");
+  if (mainLine) lines.push(mainLine);
+  lines.push(...others);
+  return lines;
+}
+var FooterPresets;
+var init_footer_builder = __esm({
+  "src/screen/footer-builder.ts"() {
+    "use strict";
+    FooterPresets = {
+      /**
+       * Menu screen footer
+       */
+      menu: (customInfo = null) => buildFooter({
+        navigation: "\u2191/\u2193 to navigate",
+        actions: "Enter to select",
+        escape: "Esc to go back",
+        info: customInfo
+      }),
+      /**
+       * Word grid footer
+       */
+      wordGrid: (totalWords) => buildFooter({
+        navigation: "\u2191\u2193\u2190\u2192 to navigate",
+        actions: "Enter to select",
+        escape: "Esc to go back",
+        info: `Total: ${totalWords} words`
+      }),
+      /**
+       * Text input footer
+       */
+      textInput: () => buildFooter({
+        actions: "Type and press Enter to submit",
+        escape: "Esc to cancel"
+      }),
+      /**
+       * Info/static screen footer
+       */
+      info: () => buildFooter({
+        escape: "Esc to continue"
+      }),
+      /**
+       * Main menu footer (escape exits)
+       */
+      mainMenu: () => buildFooter({
+        navigation: "\u2191/\u2193 to navigate",
+        actions: "Enter to select",
+        escape: "Esc to exit"
+      }),
+      /**
+       * Action menu footer (for word cards, etc.)
+       */
+      actionMenu: (hasAudio = false) => {
+        const parts = buildFooter({
+          navigation: "\u2191/\u2193 to navigate",
+          actions: "Enter to select",
+          escape: "Esc to go back"
+        });
+        if (hasAudio) {
+          parts.push("Audio available");
+        }
+        return parts;
+      }
+    };
+  }
+});
+
+// src/screen/index.ts
+var screen_exports = {};
+__export(screen_exports, {
+  Box: () => Box5,
+  Divider: () => Divider,
+  FooterPresets: () => FooterPresets,
+  GridCell: () => GridCell,
+  InputField: () => InputField,
+  ListComponent: () => ListComponent,
+  ListItem: () => ListItem,
+  MultiColumnListComponent: () => MultiColumnListComponent,
+  MultiColumnListWithPreviewComponent: () => MultiColumnListWithPreviewComponent,
+  React: () => React5,
+  ScreenBody: () => ScreenBody,
+  ScreenContainer: () => ScreenContainer,
+  ScreenDivider: () => ScreenDivider,
+  ScreenFooter: () => ScreenFooter,
+  ScreenRow: () => ScreenRow,
+  ScreenTitle: () => ScreenTitle,
+  Text: () => Text5,
+  TextBlock: () => TextBlock,
+  buildBreadcrumb: () => buildBreadcrumb,
+  buildDetailBreadcrumb: () => buildDetailBreadcrumb,
+  buildFooter: () => buildFooter,
+  h: () => createElement2,
+  load: () => load,
+  organizeFooterMessages: () => organizeFooterMessages,
+  showListScreen: () => showListScreen,
+  showMenuScreen: () => showMenuScreen,
+  showMultiColumnListScreen: () => showMultiColumnListScreen,
+  showMultiColumnListWithPreviewScreen: () => showMultiColumnListWithPreviewScreen,
+  showScreen: () => showScreen,
+  showWordGridScreen: () => showWordGridScreen,
+  useCallback: () => useCallback,
+  useEffect: () => useEffect3,
+  useInput: () => useInput2,
+  useMemo: () => useMemo,
+  useRef: () => useRef3,
+  useState: () => useState3
+});
+import React5, { useState as useState3, useEffect as useEffect3, useRef as useRef3, useMemo, useCallback, createElement as createElement2 } from "react";
+import { Box as Box5, Text as Text5, useInput as useInput2 } from "ink";
+async function load() {
+  if (loadPromise) return loadPromise;
+  loadPromise = Promise.all([
+    import("react"),
+    import("ink")
+  ]).then(() => {
+  });
+  return loadPromise;
+}
+var loadPromise;
+var init_screen = __esm({
+  "src/screen/index.ts"() {
+    "use strict";
+    init_screens();
+    init_list_components();
+    init_components();
+    init_ui_elements();
+    init_utils();
+    init_footer_builder();
+    loadPromise = null;
+    if (typeof window === "undefined") {
+      load().catch(() => {
+      });
+    }
+  }
+});
+
+// src/scripts/cli-runner.ts
+import path4 from "path";
+import { pathToFileURL } from "url";
+
+// src/args/index.ts
+import { readFileSync, existsSync } from "fs";
+import { resolve, dirname, basename, extname, join, isAbsolute } from "path";
+import { config } from "dotenv";
+var Args = class _Args {
+  args = {};
+  flags = {};
+  options = {};
+  commands = [];
+  usedKeys = /* @__PURE__ */ new Set();
+  aliases = {};
+  overrides = {};
+  defaults = {};
+  prefixes = [];
+  nots = [];
+  configValues = {};
+  configsLoaded = [];
+  env = "local";
+  constructor(contextOrConfig = {}, config2) {
+    const hasContext = config2 !== void 0;
+    const configToUse = hasContext ? config2 ?? {} : contextOrConfig ?? {};
+    const context = hasContext ? contextOrConfig : void 0;
+    this.aliases = {};
+    this.overrides = {};
+    this.defaults = {};
+    this.prefixes = ["not", "no"];
+    if (Object.keys(configToUse).length > 0) {
+      this.configure(configToUse);
+    }
+    const args = configToUse.args || process.argv.slice(2);
+    this.parseArgs(args);
+    this.env = this.get("env")?.toLowerCase() || "local";
+    this.loadDotEnv();
+    this.loadConfigFiles();
+    this.checkConflicts();
+    if (context && typeof context.registerCleanup === "function") {
+      context.registerCleanup((ctx) => {
+        const unusedArgs = ctx.args.getUnused();
+        if (unusedArgs.length > 0) {
+          ctx.logger.warn("Unused CLI args:", unusedArgs.join(", "));
+        }
+      });
+    }
+  }
+  /**
+   * Configure Args options
+   * Only parameters present in config are updated
+   * Note: Args is special - it's initialized first, so it can't take context
+   */
+  configure(config2) {
+    if (config2.aliases !== void 0) {
+      this.aliases = config2.aliases;
+    }
+    if (config2.overrides !== void 0) {
+      this.overrides = config2.overrides;
+    }
+    if (config2.defaults !== void 0) {
+      this.defaults = config2.defaults;
+    }
+    if (config2.prefixes !== void 0) {
+      this.prefixes = config2.prefixes;
+    }
+  }
+  /**
+   * Initialize Args instance.
+   * Args.init(context, config) when used from init/setup: context has registerCleanup, Args registers unused-args cleanup.
+   * Args.init(config) for standalone use (no cleanup).
+   */
+  static init(contextOrConfig, config2) {
+    if (config2 !== void 0) {
+      return new _Args(contextOrConfig, config2);
+    }
+    return new _Args(contextOrConfig ?? {});
+  }
+  /**
+   * Parse command line arguments
+   */
+  parseArgs(args) {
+    let i = 0;
+    while (i < args.length) {
+      const arg = args[i];
+      if (arg.startsWith("--")) {
+        const [key, value] = this.parseLongOption(arg);
+        this.setValue(key, value);
+        i++;
+      } else if (arg.startsWith("-")) {
+        const result = this.parseShortOption(arg, args, i);
+        if (result.consumed > 0) {
+          i += result.consumed;
+        } else {
+          i++;
+        }
+      } else {
+        this.commands.push(arg);
+        i++;
+      }
+    }
+  }
+  /**
+   * Parse long option (--key=value or --key)
+   */
+  parseLongOption(arg) {
+    const key = arg.slice(2);
+    const prefix = this.prefixes.find((p) => key.startsWith(p));
+    if (prefix) {
+      let strippedKey = key.slice(prefix.length);
+      if (strippedKey.startsWith("-")) {
+        strippedKey = strippedKey.slice(1);
+      }
+      this.nots.push(key);
+      return [strippedKey, false];
+    }
+    if (key.includes("=")) {
+      const eqIndex = key.indexOf("=");
+      const optionKey = key.slice(0, eqIndex);
+      const value = key.slice(eqIndex + 1);
+      return [optionKey, this.parseValue(value)];
+    } else {
+      return [key, true];
+    }
+  }
+  /**
+   * Parse short option (-k=value, -k, or bundled -vsd)
+   */
+  parseShortOption(arg, args, index) {
+    const key = arg.slice(1);
+    if (key.length === 1 && index + 1 < args.length && !args[index + 1].startsWith("-")) {
+      const value = args[index + 1];
+      this.setValue(key, this.parseValue(value));
+      return { consumed: 2 };
+    }
+    if (key.length > 1 && !key.includes("=")) {
+      for (let i = 0; i < key.length; i++) {
+        const shortKey = key[i];
+        if (shortKey in this.aliases) {
+          this.setValue(shortKey, true);
+        } else {
+          this.args[shortKey] = true;
+        }
+      }
+      return { consumed: 1 };
+    }
+    if (key.includes("=")) {
+      const eqIndex = key.indexOf("=");
+      const optionKey = key.slice(0, eqIndex);
+      const value = key.slice(eqIndex + 1);
+      if (optionKey.length > 1) {
+        for (let i = 0; i < optionKey.length - 1; i++) {
+          const shortKey = optionKey[i];
+          if (shortKey in this.aliases) {
+            this.setValue(shortKey, true);
+          } else {
+            this.args[shortKey] = true;
+          }
+        }
+        const lastKey = optionKey[optionKey.length - 1];
+        if (lastKey in this.aliases) {
+          this.setValue(lastKey, this.parseValue(value));
+        } else {
+          this.args[lastKey] = this.parseValue(value);
+        }
+      } else {
+        this.setValue(optionKey, this.parseValue(value));
+      }
+      return { consumed: 1 };
+    } else {
+      this.setValue(key, true);
+      return { consumed: 1 };
+    }
+  }
+  /**
+   * Parse value (handle quotes)
+   */
+  parseValue(value) {
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      return value.slice(1, -1);
+    }
+    return value;
+  }
+  /**
+   * Set a value with proper categorization
+   */
+  setValue(key, value) {
+    const resolvedKey = this.aliases[key] || key;
+    if (typeof value === "boolean") {
+      this.flags[resolvedKey] = value;
+    } else {
+      this.options[resolvedKey] = value;
+    }
+    this.args[resolvedKey.toLowerCase()] = value;
+  }
+  /**
+   * Check for conflicts (short + long form of same option)
+   */
+  checkConflicts() {
+    const conflicts = [];
+    for (const [shortKey, longKey] of Object.entries(this.aliases)) {
+      const hasShort = this.args[shortKey] !== void 0;
+      const hasLong = this.args[longKey] !== void 0;
+      if (hasShort && hasLong) {
+        conflicts.push(`Both -${shortKey} and --${longKey} specified`);
+      }
+    }
+    if (conflicts.length > 0) {
+      throw new Error(`Argument conflicts: ${conflicts.join(", ")}`);
+    }
+  }
+  /**
+   * Get a value with precedence order
+   */
+  get(key) {
+    const resolvedKey = this.aliases[key] || key;
+    const lcKey = resolvedKey.toLowerCase();
+    this.usedKeys.add(lcKey);
+    const overrideKey = Object.keys(this.overrides).find((k) => k.toLowerCase() === lcKey);
+    if (overrideKey !== void 0) {
+      return this.overrides[overrideKey];
+    }
+    const lcKeyWithEnv = `${lcKey}${this.env ? `_${this.env.toLowerCase()}` : ""}`;
+    if (this.env && this.args[lcKeyWithEnv] !== void 0) {
+      return this.args[lcKeyWithEnv];
+    } else if (this.args[lcKey] !== void 0) {
+      return this.args[lcKey];
+    }
+    const configKey = Object.keys(this.configValues).find((k) => k.toLowerCase() === lcKey);
+    if (configKey !== void 0) {
+      return this.configValues[configKey];
+    }
+    const envKey = this.toEnvKey(resolvedKey);
+    const envKeyWithEnv = `${envKey}${this.env ? `_${this.env.toUpperCase()}` : ""}`;
+    const envSpecificKey = Object.keys(process.env).find(
+      (k) => this.env && k.toUpperCase() === envKeyWithEnv
+    );
+    const envKeyFound = Object.keys(process.env).find((k) => k.toUpperCase() === envKey);
+    const envKeyAlt = envKey.replace(/_([0-9])/g, "$1");
+    const envKeyAltFound = !envKeyFound ? Object.keys(process.env).find((k) => k.toUpperCase() === envKeyAlt) : null;
+    if (envSpecificKey) {
+      return process.env[envSpecificKey];
+    } else if (envKeyFound) {
+      return process.env[envKeyFound];
+    } else if (envKeyAltFound) {
+      return process.env[envKeyAltFound];
+    }
+    const defaultKey = Object.keys(this.defaults).find((k) => k.toLowerCase() === lcKey);
+    if (defaultKey !== void 0) {
+      return this.defaults[defaultKey];
+    }
+    if (lcKey === "env" && process.env.NODE_ENV !== void 0) {
+      return process.env.NODE_ENV;
+    }
+    return void 0;
+  }
+  /**
+   * Return which layer provided the value for get(key): overrides, cli, config, env, or default.
+   * Does not add key to usedKeys. Use after get(key) when you need the origin.
+   */
+  getSource(key) {
+    const resolvedKey = this.aliases[key] || key;
+    const lcKey = resolvedKey.toLowerCase();
+    const overrideKey = Object.keys(this.overrides).find((k) => k.toLowerCase() === lcKey);
+    if (overrideKey !== void 0) return "overrides";
+    const lcKeyWithEnv = `${lcKey}${this.env ? `_${this.env.toLowerCase()}` : ""}`;
+    if (this.env && this.args[lcKeyWithEnv] !== void 0) return "cli";
+    if (this.args[lcKey] !== void 0) return "cli";
+    const configKey = Object.keys(this.configValues).find((k) => k.toLowerCase() === lcKey);
+    if (configKey !== void 0) return "config";
+    const envKey = this.toEnvKey(resolvedKey);
+    const envKeyWithEnv = `${envKey}${this.env ? `_${this.env.toUpperCase()}` : ""}`;
+    const envSpecificKey = Object.keys(process.env).find((k) => this.env && k.toUpperCase() === envKeyWithEnv);
+    const envKeyFound = Object.keys(process.env).find((k) => k.toUpperCase() === envKey);
+    const envKeyAlt = envKey.replace(/_([0-9])/g, "$1");
+    const envKeyAltFound = !envKeyFound ? Object.keys(process.env).find((k) => k.toUpperCase() === envKeyAlt) : null;
+    if (envSpecificKey || envKeyFound || envKeyAltFound) return "env";
+    const defaultKey = Object.keys(this.defaults).find((k) => k.toLowerCase() === lcKey);
+    if (defaultKey !== void 0) return "default";
+    if (lcKey === "env" && process.env.NODE_ENV !== void 0) return "env";
+    return void 0;
+  }
+  /**
+   * Set a value (for testing/internal use)
+   */
+  set(key, value) {
+    this.args[key] = value;
+  }
+  /**
+   * Check if a command exists (case-insensitive)
+   */
+  hasCommand(cmd) {
+    return this.commands.some((command) => command.toLowerCase() === cmd.toLowerCase());
+  }
+  /**
+   * Get all commands
+   */
+  getCommands() {
+    return [...this.commands];
+  }
+  /**
+   * Get used keys (as array)
+   */
+  getUsed() {
+    return Array.from(this.usedKeys);
+  }
+  /**
+   * Get unused keys (as array)
+   */
+  getUnused() {
+    const unused = [];
+    for (const key of Object.keys(this.args)) {
+      if (!this.usedKeys.has(key) && !this.nots.includes(key)) {
+        unused.push(key);
+      }
+    }
+    return unused;
+  }
+  /**
+   * Convert key to environment variable format
+   * Converts camelCase to SNAKE_CASE
+   */
+  toEnvKey(key) {
+    if (key.includes("_") && key === key.toUpperCase()) {
+      return key;
+    }
+    return key.replace(
+      /[A-Z0-9]/g,
+      (match, offset) => offset === 0 ? match : "_" + match.toLowerCase()
+    ).toUpperCase();
+  }
+  /**
+   * Load .env file
+   */
+  loadDotEnv() {
+    const dotEnvPath = this.get("dotEnvPath") || process.cwd();
+    const dotEnvFile = this.get("dotEnvFile") || ".env";
+    if (this.get("dotEnvFile")) {
+      const customPath = resolve(dotEnvPath, dotEnvFile);
+      if (existsSync(customPath)) {
+        config({ path: customPath, quiet: true });
+      }
+      return;
+    }
+    let dotEnvPathFile = null;
+    const envSpecificFile = `.env.${this.env}`;
+    const envSpecificPath = resolve(dotEnvPath, envSpecificFile);
+    if (existsSync(envSpecificPath)) {
+      dotEnvPathFile = envSpecificPath;
+    }
+    if (!dotEnvPathFile && !this.get("dotEnvPath")) {
+      const examplesPath = resolve(dotEnvPath, "examples");
+      const examplesEnvSpecificPath = resolve(examplesPath, envSpecificFile);
+      if (existsSync(examplesEnvSpecificPath)) {
+        dotEnvPathFile = examplesEnvSpecificPath;
+      }
+    }
+    if (!dotEnvPathFile) {
+      dotEnvPathFile = resolve(dotEnvPath, dotEnvFile);
+      if (!existsSync(dotEnvPathFile)) {
+        if (!this.get("dotEnvPath")) {
+          const examplesPath = resolve(dotEnvPath, "examples");
+          const examplesEnvFile = resolve(examplesPath, dotEnvFile);
+          if (existsSync(examplesEnvFile)) {
+            dotEnvPathFile = examplesEnvFile;
+          } else {
+            dotEnvPathFile = resolve(dotEnvPath, "..", dotEnvFile);
+          }
+        }
+      }
+    }
+    if (dotEnvPathFile && existsSync(dotEnvPathFile)) {
+      config({ path: dotEnvPathFile, quiet: true });
+    }
+  }
+  /**
+   * Load configuration files
+   */
+  loadConfigFiles() {
+    this.configsLoaded = [];
+    this.configValues = {};
+    const _defaultConfigExtension = this.get("defaultConfigExtension") || "js";
+    const optConfigFiles = this.get("config") || this.get("configs") || "";
+    const configFiles = optConfigFiles ? optConfigFiles.split(/,\s*/) : [];
+    const optConfigFilePath = this.get("configPath");
+    if (configFiles.length > 0) {
+      for (const cfgFile of configFiles) {
+        let notLoaded = false;
+        let notLoadedEnvSpecific = false;
+        const cfgFileWithPath = this.resolveFileWithPath(optConfigFilePath, cfgFile);
+        try {
+          const cfgContents = this.requireConfigFile(cfgFileWithPath);
+          this.configValues = { ...this.configValues, ...cfgContents };
+          this.configsLoaded.push(cfgFileWithPath);
+        } catch {
+          notLoaded = true;
+        }
+        const cfgEnvFileWithPath = this.resolveFileWithPath(
+          optConfigFilePath,
+          cfgFile,
+          this.env
+        );
+        if (cfgEnvFileWithPath !== cfgFileWithPath) {
+          try {
+            const cfgContents = this.requireConfigFile(cfgEnvFileWithPath);
+            this.configValues = { ...this.configValues, ...cfgContents };
+            this.configsLoaded.push(cfgEnvFileWithPath);
+          } catch {
+            notLoadedEnvSpecific = true;
+          }
+        } else {
+          notLoadedEnvSpecific = true;
+        }
+        if (notLoaded && notLoadedEnvSpecific) {
+          throw new Error(`can't load config file "${cfgFileWithPath}"`);
+        }
+      }
+    }
+  }
+  /**
+   * Resolve file path with environment-specific naming
+   */
+  resolveFileWithPath(optConfigFilePath, cfgFile, env) {
+    let cfgFileWithPath = optConfigFilePath ? isAbsolute(optConfigFilePath) ? resolve(optConfigFilePath, cfgFile) : resolve(process.cwd(), optConfigFilePath, cfgFile) : isAbsolute(cfgFile) ? cfgFile : resolve(process.cwd(), cfgFile);
+    const { basePathWithName, extension } = this.splitPath(cfgFileWithPath);
+    if (env) {
+      cfgFileWithPath = `${basePathWithName}.${env}.${extension || "js"}`;
+    } else {
+      cfgFileWithPath = `${basePathWithName}.${extension || "js"}`;
+    }
+    return cfgFileWithPath;
+  }
+  /**
+   * Split file path into base path and extension
+   */
+  splitPath(filePath) {
+    const basePathWithName = join(dirname(filePath), basename(filePath, extname(filePath)));
+    const extension = extname(filePath).slice(1);
+    return { basePathWithName, extension };
+  }
+  /**
+   * Require a configuration file (supports .js and .json)
+   */
+  requireConfigFile(filePath) {
+    if (!existsSync(filePath)) {
+      throw new Error(`Config file not found: ${filePath}`);
+    }
+    const ext = extname(filePath).toLowerCase();
+    if (ext === ".json") {
+      const content = readFileSync(filePath, "utf8");
+      return JSON.parse(content);
+    } else if (ext === ".js") {
+      try {
+        delete __require.cache[__require.resolve(filePath)];
+        return __require(filePath);
+      } catch (error) {
+        throw new Error(`Failed to load JS config file: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    } else {
+      throw new Error(`Unsupported file extension: ${ext}`);
+    }
+  }
+  /**
+   * Get all parsed data
+   */
+  getParsed() {
+    return {
+      command: this.commands[0] || "",
+      flags: { ...this.flags },
+      options: { ...this.options },
+      usedKeys: Array.from(this.usedKeys)
+    };
+  }
+  /**
+   * Set prefixes dynamically and re-parse arguments (like legacy)
+   */
+  setPrefixes(prefixes) {
+    const arr = Array.isArray(prefixes) ? prefixes : prefixes.split(/,\s*/);
+    const sortedArr = arr.sort(
+      (a, b) => a.length < b.length ? 1 : a.length > b.length ? -1 : 0
+    );
+    this.prefixes = sortedArr.map((el) => el.toLowerCase());
+    const args = process.argv.slice(2);
+    this.parseArgs(args);
+  }
+};
+
+// src/params/index.ts
+import Joi from "joi";
+
+// src/errors.ts
+var FrameworkError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FrameworkError";
+  }
+};
+var ParamError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "ParamError";
+  }
+};
+var InitError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "InitError";
+  }
+};
+var FileDatabaseError = class extends FrameworkError {
+  constructor(message) {
+    super(message);
+    this.name = "FileDatabaseError";
+  }
+};
+
+// src/params/custom-types.ts
+var joiEdateType = (value, helpers) => {
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(value)) {
+    const testDate = new Date(value);
+    if (!isNaN(testDate.getTime())) {
+      return value;
+    }
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value !== "string") {
+    value = String(value);
+  }
+  if (value.toLowerCase() === "now") {
+    return (/* @__PURE__ */ new Date()).toISOString();
+  }
+  const referenceRegex = /^@(\w+)([+-]\d+[smhdwy])$/i;
+  const referenceMatch = value.match(referenceRegex);
+  if (referenceMatch) {
+    const [, paramName, relativeExpr] = referenceMatch;
+    const context = helpers.prefs?.context;
+    if (!context || !context.params) {
+      throw new ParamError(`Cannot resolve cross-parameter reference @${paramName}: context not available. Ensure parameters are processed with proper context.`);
+    }
+    const referencedValue = context.params[paramName];
+    if (referencedValue === void 0 || referencedValue === null) {
+      throw new ParamError(`Cannot resolve @${paramName}: parameter "${paramName}" is not defined or has no value. Parameters are evaluated left-to-right.`);
+    }
+    let referenceDate;
+    if (referencedValue instanceof Date) {
+      referenceDate = referencedValue;
+    } else if (typeof referencedValue === "string") {
+      referenceDate = new Date(referencedValue);
+      if (isNaN(referenceDate.getTime())) {
+        throw new ParamError(`Referenced parameter @${paramName} has invalid date value: ${referencedValue}`);
+      }
+    } else {
+      throw new ParamError(`Referenced parameter @${paramName} is not a valid date type (found: ${typeof referencedValue})`);
+    }
+    const relativeMatch2 = relativeExpr.match(/^([+-])(\d+)([smhdwy])$/i);
+    if (!relativeMatch2) {
+      throw new ParamError(`Invalid relative time expression in @${paramName}${relativeExpr}`);
+    }
+    const [, sign, amount, unit] = relativeMatch2;
+    const offset = calculateTimeOffset(parseInt(amount, 10), unit, sign);
+    const resultDate = new Date(referenceDate.getTime() + offset);
+    return resultDate.toISOString();
+  }
+  const relativeTimeRegex = /^([+-])(\d+)([smhdwy])$/i;
+  const relativeMatch = value.match(relativeTimeRegex);
+  if (relativeMatch) {
+    const [, sign, amount, unit] = relativeMatch;
+    const numAmount = parseInt(amount, 10);
+    if (isNaN(numAmount)) {
+      throw new ParamError(`Invalid relative time amount: ${amount}`);
+    }
+    const offset = calculateTimeOffset(numAmount, unit, sign);
+    const resultDate = new Date(Date.now() + offset);
+    return resultDate.toISOString();
+  }
+  const parsedDate = new Date(value);
+  if (isNaN(parsedDate.getTime())) {
+    throw new ParamError(`Invalid date format: ${value}. Expected a valid date string, "now", relative time expression (e.g., "-2h", "+1d"), or cross-parameter reference (e.g., "@startTime+2h")`);
+  }
+  return parsedDate.toISOString();
+};
+function calculateTimeOffset(amount, unit, sign) {
+  let multiplier = 1;
+  switch (unit.toLowerCase()) {
+    case "s":
+      multiplier = 1e3;
+      break;
+    case "m":
+      multiplier = 60 * 1e3;
+      break;
+    case "h":
+      multiplier = 60 * 60 * 1e3;
+      break;
+    case "d":
+      multiplier = 24 * 60 * 60 * 1e3;
+      break;
+    case "w":
+      multiplier = 7 * 24 * 60 * 60 * 1e3;
+      break;
+    case "y":
+      multiplier = 365 * 24 * 60 * 60 * 1e3;
+      break;
+    default:
+      throw new ParamError(`Invalid time unit: ${unit}. Supported units: s, m, h, d, w, y`);
+  }
+  return sign === "+" ? amount * multiplier : -amount * multiplier;
+}
+var joiStringArrayType = (type) => (value, helpers) => {
+  if (value === void 0 || typeof value === "function") {
+    return [];
+  }
+  const arr = value.split(/,\s*/).map((el) => {
+    if (type === "number") {
+      const v = parseInt(el, 10);
+      if (isNaN(v)) {
+        throw new ParamError(`array element "${el}" should be numeric`);
+      }
+      return v;
+    } else if (type === "boolean") {
+      const v = el.match(/true|t|yes|1/i) ? true : el.match(/false|f|no|0/i) ? false : null;
+      if (v === null) {
+        throw new ParamError(`array element "${el}" should be boolean`);
+      }
+      return v;
+    } else if (type === "string") {
+      return el;
+    } else {
+      throw new ParamError(`unknown type "${type}" for array elements`);
+    }
+  });
+  return arr;
+};
+
+// src/params/index.ts
+var Params = class _Params {
+  context;
+  // Partial context during initialization
+  params = {};
+  paramSources = {};
+  definitions = {};
+  args;
+  paramSetters = [];
+  paramGetters = [];
+  trackedParams = [];
+  _currentModule = "script";
+  /** Resolved early in constructor so cleanup does not read params lazily */
+  _showUsedParams = false;
+  constructor(context, options = {}) {
+    this.context = context;
+    this.args = context.args;
+    if (Object.keys(options).length > 0) {
+      this.configure(options);
+    }
+    this._showUsedParams = this.get("showUsedParams", "boolean default false");
+    if (context && typeof context.registerCleanup === "function") {
+      context.registerCleanup((ctx) => {
+        if (!ctx.params.getShowUsedParams()) return;
+        const byModule = ctx.params.getFiguredByModule();
+        const modules = Object.keys(byModule).sort();
+        if (modules.length === 0) return;
+        const logger = ctx.logger;
+        logger.debug("[Params]: list of used params:");
+        if (typeof logger.highlight !== "function") {
+          for (const mod of modules) {
+            logger.debug(`  [${mod}]`);
+            for (const [key, entry] of Object.entries(byModule[mod])) {
+              logger.debug(`    ${key}: ${JSON.stringify(entry.value)} (${entry.source})`);
+            }
+          }
+          return;
+        }
+        for (const mod of modules) {
+          logger.debug(`  [${mod}]`);
+          for (const [key, entry] of Object.entries(byModule[mod])) {
+            const valueStr = JSON.stringify(entry.value);
+            const display = entry.source === "default" ? valueStr : logger.highlight(valueStr);
+            logger.debug(`    ${key}: ${display} (${entry.source})`);
+          }
+        }
+      });
+    }
+  }
+  /** Whether --showUsedParams was requested (resolved in constructor). */
+  getShowUsedParams() {
+    return this._showUsedParams;
+  }
+  /**
+   * Configure parameters
+   * Only parameters present in options are updated
+   */
+  configure(options) {
+    for (const [k, v] of Object.entries(options)) {
+      this.params[k] = v;
+    }
+  }
+  /**
+   * Initialize Params from context and CLI parameters
+   * Note: Params is special - it's initialized early with partial context
+   */
+  static init(context, options) {
+    return new _Params(context, options || {});
+  }
+  /**
+   * Track a parameter request for --stopAfter=init and --showUsedParams
+   */
+  trackParam(key, definition, value, source, moduleName) {
+    this.trackedParams.push({
+      key,
+      definition,
+      value,
+      source,
+      module: moduleName ?? this._currentModule
+    });
+  }
+  /**
+   * Get all tracked parameters (for --stopAfter=init)
+   */
+  getTrackedParams() {
+    return [...this.trackedParams];
+  }
+  /**
+   * Get all figured parameters as a record (flat, last occurrence per key)
+   * Returns all parameters that were collected during initialization,
+   * whether from CLI args, options, or defaults
+   */
+  getAllFigured() {
+    const result = {};
+    for (const param of this.trackedParams) {
+      result[param.key] = {
+        value: param.value,
+        source: param.source
+      };
+    }
+    return result;
+  }
+  /**
+   * Get figured parameters grouped by module name.
+   * Same param can appear in multiple modules (e.g. source, resource).
+   */
+  getFiguredByModule() {
+    const byModule = {};
+    for (const param of this.trackedParams) {
+      const mod = param.module;
+      if (!byModule[mod]) byModule[mod] = {};
+      byModule[mod][param.key] = { value: param.value, source: param.source };
+    }
+    return byModule;
+  }
+  /**
+   * Clear tracked parameters
+   */
+  clearTrackedParams() {
+    this.trackedParams = [];
+  }
+  /**
+   * Assign a parameter definition
+   */
+  assignDefinition(key, definition) {
+    if (this.definitions[key] && !definition) {
+      return this.definitions[key];
+    }
+    let type;
+    if (!definition) {
+      type = Joi.string();
+    } else if (Joi.isSchema(definition)) {
+      type = definition;
+    } else if (Joi.isSchema(definition.type)) {
+      type = definition.type;
+    } else if (typeof definition === "string") {
+      type = this.toJoi(definition);
+    } else if (typeof definition.type === "string") {
+      type = this.toJoi(definition.type);
+    } else if (!definition.type) {
+      type = Joi.string();
+    } else {
+      type = Joi.string();
+    }
+    if (!this.definitions[key]) {
+      this.definitions[key] = {};
+    }
+    this.definitions[key].type = type;
+    if (definition && definition.values) {
+      if (Array.isArray(definition.values)) {
+        this.definitions[key].values = definition.values;
+      }
+    }
+    return this.definitions[key];
+  }
+  /**
+   * Convert string definition to Joi schema
+   */
+  toJoi(str) {
+    let type;
+    if (str.match(/^string|^text/i)) {
+      type = Joi.string();
+    } else if (str.match(/^number|^integer|^int/i)) {
+      type = Joi.number();
+    } else if (str.match(/^boolean|^bool/i)) {
+      type = Joi.boolean();
+    } else if (str.match(/^date/i)) {
+      type = Joi.custom(joiEdateType);
+    } else if (str.match(/^duration/i)) {
+      type = Joi.string().isoDuration();
+    } else if (str.match(/^array/i)) {
+      let elementTypes = "string";
+      const tmp = str.match(/\((.*)\)/);
+      if (tmp && tmp[1].match(/string/i)) {
+        elementTypes = "string";
+      } else if (tmp && tmp[1].match(/number|integer|int/i)) {
+        elementTypes = "number";
+      } else if (tmp && tmp[1].match(/boolean|bool/i)) {
+        elementTypes = "boolean";
+      }
+      type = Joi.custom(joiStringArrayType(elementTypes));
+    } else {
+      type = Joi.string();
+    }
+    const regexForDefault = /\bdefault\s+([^\s]+)/;
+    const matchForDefault = str.match(regexForDefault);
+    if (matchForDefault) {
+      const defValObj = type.validate(matchForDefault[1]);
+      if (defValObj.error) {
+        throw new ParamError(`default value "${defValObj.value}" type mismatch`);
+      }
+      type = type.default(defValObj.value);
+    } else if (str.match(/required/)) {
+      type = type.required();
+    } else {
+      type = type.optional();
+    }
+    return type;
+  }
+  /**
+   * Validate a value against a definition
+   */
+  validate(key, val, def) {
+    const normalizedVal = val === null ? void 0 : val;
+    const { value, error } = def.type.validate(normalizedVal, {
+      context: { params: this.params },
+      abortEarly: false,
+      allowUnknown: false
+    });
+    if (error) {
+      const errs = error.details.map((el) => el.message).join(", ");
+      throw new ParamError(`"${key}" validation error: ${errs}`);
+    }
+    return value;
+  }
+  /**
+   * Get a parameter value with validation
+   */
+  get(key, definition) {
+    const def = this.assignDefinition(key, definition);
+    let valFromGetters = void 0;
+    if (def.volatile || true) {
+      valFromGetters = this.runAllRegisteredGetters(key);
+    }
+    const valFromArgs = this.args.get(key);
+    const valFromParams = this.params[key];
+    let source = "default";
+    let value;
+    if (valFromGetters !== void 0 && valFromGetters !== null) {
+      value = this.validate(key, valFromGetters, def);
+      source = "options";
+    } else if (valFromArgs !== void 0 && valFromArgs !== null) {
+      value = this.validate(key, valFromArgs, def);
+      const argsSource = this.args.getSource?.(key);
+      if (argsSource === "overrides") source = "options";
+      else if (argsSource === "cli" || argsSource === "env" || argsSource === "config") source = argsSource;
+      else if (argsSource === "default") source = "default";
+      else source = "cli";
+    } else if (valFromParams !== void 0 && valFromParams !== null) {
+      value = this.validate(key, valFromParams, def);
+      source = this.paramSources[key] ?? "options";
+    } else {
+      value = this.validate(key, void 0, def);
+      source = "default";
+    }
+    this.paramSources[key] = source;
+    this.trackParam(key, definition || "string", value, source);
+    if (value !== void 0 && def.values && !def.values.includes(value)) {
+      throw new ParamError(`key ${key} should be one of ${def.values}`);
+    }
+    return value;
+  }
+  /**
+   * Set a parameter value with validation
+   */
+  set(key, val, definition) {
+    if (val && val.type && val.value) {
+      definition = val;
+      val = val.value;
+    }
+    const def = this.assignDefinition(key, definition);
+    if (!this.runAllRegisteredSetters(key, val)) {
+      this.params[key] = val;
+    }
+  }
+  /**
+   * Get all parameters from definitions (main script).
+   * Same as getAllForModule("script", defs). Processes left-to-right for cross-parameter references.
+   */
+  getAll(defs2) {
+    return this.getAllForModule("script", defs2);
+  }
+  /**
+   * Get all parameters from definitions for a given module name.
+   * Figured params are grouped by module when using --showUsedParams.
+   * Processes parameters left-to-right to support cross-parameter references.
+   * If moduleName is omitted, it is inferred from the caller's file path (directory name under src/).
+   */
+  getAllForModule(moduleNameOrDefs, defs2) {
+    let moduleName;
+    let definitions;
+    if (defs2 !== void 0) {
+      moduleName = moduleNameOrDefs;
+      definitions = defs2;
+    } else {
+      definitions = moduleNameOrDefs;
+      moduleName = this._inferModuleNameFromStack();
+    }
+    const prev = this._currentModule;
+    this._currentModule = moduleName;
+    try {
+      const res = {};
+      for (const [k, def] of Object.entries(definitions)) {
+        const value = this.get(k, def);
+        res[k] = value;
+        if (value !== void 0) {
+          this.params[k] = value;
+        }
+      }
+      return res;
+    } finally {
+      this._currentModule = prev;
+    }
+  }
+  /**
+   * Infer module name from call stack: first caller outside params/index gives path like .../src/<moduleName>/...
+   */
+  _inferModuleNameFromStack() {
+    const stack = new Error().stack;
+    if (!stack) return "script";
+    const lines = stack.split("\n");
+    const paramsIndexPath = "params" + (typeof process !== "undefined" && process.platform === "win32" ? "\\" : "/") + "index.";
+    for (const line of lines) {
+      const parenMatch = line.match(/\(([^)]+)\)/);
+      if (!parenMatch) continue;
+      const parts = parenMatch[1].split(":");
+      if (parts.length < 3) continue;
+      const path5 = parts.slice(0, -2).join(":").replace(/^file:\/\//, "");
+      if (!path5 || path5.includes(paramsIndexPath)) continue;
+      const srcMatch = path5.match(/[/\\]src[/\\]([^/\\]+)(?:[/\\]|$)/);
+      if (srcMatch) return srcMatch[1];
+    }
+    return "script";
+  }
+  /**
+   * Run all registered getters for a key
+   */
+  runAllRegisteredGetters(key) {
+    let val = void 0;
+    for (const getter of this.paramGetters) {
+      val = getter(key, this.definitions[key]);
+      if (val !== void 0 && val !== null) {
+        break;
+      }
+    }
+    return val;
+  }
+  /**
+   * Run all registered setters for a key
+   */
+  runAllRegisteredSetters(key, value) {
+    let setterUsed = false;
+    for (const setter of this.paramSetters) {
+      setterUsed = setter(key, value);
+      if (setterUsed) {
+        break;
+      }
+    }
+    return setterUsed;
+  }
+  /**
+   * Register a parameter getter
+   */
+  registerParamGetter(fn) {
+    this.paramGetters.push(fn);
+  }
+  /**
+   * Register a parameter setter
+   */
+  registerParamSetter(fn) {
+    this.paramSetters.push(fn);
+  }
+};
+
+// src/logger/index.ts
+import chalk from "chalk";
+import util from "util";
+
+// src/logger/transports.ts
+var ConsoleTransport = class {
+  write(payload) {
+    console.info(payload);
+  }
+};
+var ParentProcessTransport = class {
+  write(payload) {
+    if (process.env.VITEST || process.env.NODE_ENV === "test") {
+      console.info(payload);
+      return;
+    }
+    if (typeof process.send === "function" && process.connected === true) {
+      process.send(payload);
+    } else {
+      console.info(payload);
+    }
+  }
+};
+
+// src/logger/index.ts
+var ALL_LEVELS = [
+  "silly",
+  "debug",
+  "logic",
+  "info",
+  "notice",
+  "warn",
+  "error",
+  "results",
+  "request",
+  "response",
+  "progress"
+];
+var DEFAULT_LEVELS = ALL_LEVELS.filter((l) => l !== "silly");
+var MAX_LEVEL_LENGTH = Math.max(...ALL_LEVELS.map((level) => level.toUpperCase().length));
+var LEVEL_COLORS = {
+  error: chalk.red.bold,
+  warn: chalk.rgb(255, 165, 0),
+  notice: chalk.cyan,
+  info: chalk.white.bold,
+  logic: chalk.gray,
+  debug: chalk.gray,
+  silly: chalk.gray,
+  request: chalk.green,
+  response: chalk.yellow,
+  progress: chalk.green,
+  results: chalk.magenta
+};
+var Logger = class _Logger {
+  context;
+  // Partial context during initialization
+  options;
+  transport;
+  startTimes = {};
+  lastProgressTimes = {};
+  constructor(context, options = {}) {
+    this.context = context;
+    this.options = this.getDefaultOptions();
+    if (options) {
+      this.configure(options);
+    }
+    this.updateTransport();
+  }
+  /**
+   * Configure logger options. Accepts both LoggerOptions shape and flat param names (levels string, progressWithTimes, progressThrottleMs).
+   */
+  configure(options) {
+    if (options.mode !== void 0) {
+      this.options.mode = this.isValidMode(options.mode) ? options.mode : "text";
+    }
+    if (options.route !== void 0) {
+      this.options.route = options.route;
+      this.updateTransport();
+    }
+    if (options.prefix !== void 0) this.options.prefix = options.prefix;
+    if (options.silent !== void 0) this.options.silent = options.silent;
+    if (options.showLevel !== void 0) this.options.showLevel = options.showLevel;
+    if (options.timestamp !== void 0) this.options.timestamp = options.timestamp;
+    if (options.levels !== void 0) {
+      const levels = typeof options.levels === "string" ? options.levels.split(",") : options.levels;
+      this.options.levels = this.normalizeLevels(levels);
+    }
+    if (options.progress !== void 0) {
+      if (options.progress.withTimes !== void 0) this.options.progressTimes = options.progress.withTimes;
+      if (options.progress.throttleMs !== void 0) this.options.progressThrottle = options.progress.throttleMs;
+    }
+    const flat = options;
+    if (flat.progressWithTimes !== void 0) this.options.progressTimes = flat.progressWithTimes;
+    if (flat.progressThrottleMs !== void 0) this.options.progressThrottle = flat.progressThrottleMs;
+  }
+  /**
+   * Initialize logger from context and CLI parameters. Whatever is in options goes (after discovered params).
+   */
+  static init(context, options) {
+    const paramDefs = {
+      mode: "string default text",
+      route: "string default console",
+      prefix: "string",
+      silent: "boolean default false",
+      showLevel: "boolean default true",
+      timestamp: "boolean default false",
+      levels: "string",
+      progressWithTimes: "boolean default false",
+      progressThrottleMs: "number"
+    };
+    const discovered = context.params.getAllForModule(paramDefs);
+    const config2 = { ...discovered, ...options };
+    const logger = new _Logger(context, config2);
+    context.logger = logger;
+    return logger;
+  }
+  getDefaultOptions() {
+    return {
+      mode: "text",
+      route: this.shouldUseIpcRoute() ? "ipc" : "console",
+      prefix: void 0,
+      silent: false,
+      showLevel: false,
+      timestamp: false,
+      levels: DEFAULT_LEVELS,
+      progressTimes: false,
+      progressThrottle: void 0
+    };
+  }
+  updateTransport() {
+    this.transport = this.options.route === "ipc" ? new ParentProcessTransport() : new ConsoleTransport();
+  }
+  setMode(mode) {
+    if (!this.isValidMode(mode)) {
+      throw new Error(`Unsupported logger mode: ${mode}`);
+    }
+    this.options.mode = mode;
+  }
+  /** Returns a styled string (bright white) for highlighting; keeps chalk inside logger. */
+  highlight(text) {
+    return chalk.whiteBright(text);
+  }
+  debug(message, ...chunks) {
+    this.out({ level: "debug", message, chunks });
+  }
+  info(message, ...chunks) {
+    this.out({ level: "info", message, chunks });
+  }
+  notice(message, ...chunks) {
+    this.out({ level: "notice", message, chunks });
+  }
+  warn(message, ...chunks) {
+    this.out({ level: "warn", message, chunks });
+  }
+  error(message, ...chunks) {
+    this.out({ level: "error", message, chunks });
+  }
+  logic(message, ...chunks) {
+    this.out({ level: "logic", message, chunks });
+  }
+  silly(message, ...chunks) {
+    this.out({ level: "silly", message, chunks });
+  }
+  results(results) {
+    this.out({ level: "results", message: "results", results });
+  }
+  request(operation, ...chunks) {
+    const message = this.inspectChunks([operation, ...chunks]);
+    this.out({ level: "request", message });
+  }
+  response(operation, ...chunks) {
+    const message = this.inspectChunks([operation, ...chunks]);
+    this.out({ level: "response", message });
+  }
+  progress(message, opts) {
+    const { prefix, count, total } = opts;
+    const paddedTotal = String(total).length;
+    const paddedCount = String(count).padStart(paddedTotal, " ");
+    const payload = {
+      level: "progress",
+      message,
+      count: paddedCount,
+      total,
+      prefix
+    };
+    if (!this.startTimes[prefix ?? ""]) {
+      this.startTimes[prefix ?? ""] = Date.now();
+    }
+    if (this.options.progressTimes) {
+      const elapsedSeconds = (Date.now() - this.startTimes[prefix ?? ""]) / 1e3;
+      let remaining = -1;
+      if (count > 1) {
+        const rate = elapsedSeconds / (count - 1);
+        remaining = (total - count) * rate;
+      }
+      payload.elapsed = this.round(elapsedSeconds, 2);
+      payload.remaining = remaining >= 0 ? this.round(remaining, 2) : remaining;
+    }
+    if (count >= total) {
+      delete this.startTimes[prefix ?? ""];
+      delete this.lastProgressTimes[prefix ?? ""];
+    }
+    if (this.shouldOutputProgress(prefix ?? "", count, total)) {
+      this.out(payload);
+      if (this.options.progressThrottle && prefix) {
+        this.lastProgressTimes[prefix] = Date.now();
+      }
+    }
+  }
+  shouldOutputProgress(prefix, count, total) {
+    if (!this.options.progressThrottle) {
+      return true;
+    }
+    if (count === 1 || count === total || !prefix) {
+      return true;
+    }
+    const lastTime = this.lastProgressTimes[prefix];
+    if (!lastTime) {
+      return true;
+    }
+    return Date.now() - lastTime >= this.options.progressThrottle;
+  }
+  out(struct) {
+    if (this.options.silent) {
+      return;
+    }
+    if (!this.options.levels.includes(struct.level)) {
+      return;
+    }
+    if (this.options.prefix && !struct.prefix) {
+      struct.prefix = this.options.prefix;
+    }
+    const output = this.options.mode === "json" ? struct : this.formatLog(struct);
+    this.transport.write(output);
+  }
+  formatLog(struct) {
+    const parts = [];
+    const now = /* @__PURE__ */ new Date();
+    if (this.options.timestamp) {
+      parts.push(now.toISOString());
+    }
+    if (this.options.showLevel) {
+      parts.push(struct.level.toUpperCase().padEnd(MAX_LEVEL_LENGTH));
+    }
+    if (struct.level === "progress") {
+      if (struct.prefix) {
+        parts.push(LEVEL_COLORS[struct.level].bold(struct.prefix));
+      }
+      if (struct.count !== void 0 && struct.total !== void 0) {
+        parts.push(LEVEL_COLORS[struct.level](`${struct.count}/${struct.total}`));
+      }
+    } else if (struct.prefix) {
+      parts.push(chalk.cyan(`[${struct.prefix}]`));
+    }
+    if (struct.message) {
+      const formatter = LEVEL_COLORS[struct.level] ?? chalk.white;
+      parts.push(formatter.bold(struct.message));
+    }
+    if (struct.level === "progress") {
+      if (struct.elapsed !== void 0 && struct.remaining !== void 0) {
+        const formatter = LEVEL_COLORS[struct.level];
+        parts.push(formatter(`${struct.elapsed}/${struct.remaining}`));
+      }
+    }
+    if (struct.chunks && struct.chunks.length) {
+      parts.push(this.inspectChunks(struct.chunks));
+    }
+    if (struct.results) {
+      const formatter = LEVEL_COLORS[struct.level] ?? chalk.white;
+      parts.push(formatter(JSON.stringify(struct.results, null, 4)));
+    }
+    return parts.join(" ");
+  }
+  inspectChunks(chunks) {
+    return chunks.map((chunk) => util.inspect(chunk, { colors: true, depth: null })).join(" ");
+  }
+  shouldUseIpcRoute() {
+    if (process.env.VITEST || process.env.NODE_ENV === "test") {
+      return false;
+    }
+    return typeof process.send === "function" && process.connected === true;
+  }
+  normalizeLevels(levels) {
+    if (!levels || !levels.length) {
+      return DEFAULT_LEVELS;
+    }
+    const tokens = levels.map((t) => String(t).trim()).filter(Boolean);
+    const explicitIncludes = tokens.filter((t) => !t.startsWith("+") && !t.startsWith("-")).map((t) => t);
+    const addIncludes = tokens.filter((t) => t.startsWith("+")).map((t) => t.slice(1));
+    const excludes = tokens.filter((t) => t.startsWith("-")).map((t) => t.slice(1));
+    const unknown = [...explicitIncludes, ...addIncludes, ...excludes].filter((level) => !ALL_LEVELS.includes(level));
+    if (unknown.length) {
+      console.warn(`[Logger] Unknown level(s): ${unknown.join(", ")}`);
+    }
+    const base = explicitIncludes.length ? explicitIncludes : Array.from(/* @__PURE__ */ new Set([...DEFAULT_LEVELS, ...addIncludes]));
+    return base.filter((level) => !excludes.includes(level));
+  }
+  isValidMode(mode) {
+    return mode === void 0 || mode === null || mode === "text" || mode === "json";
+  }
+  round(value, places) {
+    const factor = Math.pow(10, places);
+    return Math.round(value * factor) / factor;
+  }
+};
+
+// src/init/index.ts
+import { EventEmitter } from "events";
+function extractComponentOptions(opts, componentName) {
+  const reservedKeys = ["overrides", "defaults", "modules"];
+  const componentOptions = {};
+  for (const [key, value] of Object.entries(opts)) {
+    if (!reservedKeys.includes(key)) {
+      componentOptions[key] = value;
+    }
+  }
+  return componentOptions;
+}
+function setup(opts = {}) {
+  const partialContext = {
+    emitter: new EventEmitter(),
+    isStop: () => false,
+    cleanupFunctions: [],
+    registerCleanup: (fn) => {
+      partialContext.cleanupFunctions.push(fn);
+    }
+  };
+  const args = Args.init(partialContext, {
+    overrides: opts.overrides || {},
+    defaults: opts.defaults || {}
+  });
+  partialContext.args = args;
+  const params = Params.init(partialContext, opts.overrides || {});
+  partialContext.params = params;
+  const loggerOptions = extractComponentOptions(opts, "logger");
+  const logger = Logger.init(partialContext, loggerOptions);
+  partialContext.logger = logger;
+  const context = {
+    args,
+    params,
+    logger,
+    emitter: partialContext.emitter,
+    isStop: partialContext.isStop,
+    cleanupFunctions: partialContext.cleanupFunctions,
+    registerCleanup: partialContext.registerCleanup
+  };
+  logger.debug("[setup] completed successfully");
+  return context;
+}
+async function setupModules(context, opts = {}) {
+  if (opts.modules && opts.modules.length > 0) {
+    context.logger.debug(`[setupModules] modules specified: ${opts.modules.join(", ")} (not yet implemented)`);
+  }
+  context.logger.debug("[setupModules] completed successfully");
+  return context;
+}
+function printAllParameters(context) {
+  const trackedParams = context.params.getTrackedParams();
+  console.log("\n=== All Figured Parameters ===");
+  console.log("\nComponent: Logger");
+  const loggerParams = trackedParams.filter(
+    (p) => ["mode", "route", "prefix", "silent", "showLevel", "timestamp", "levels"].includes(p.key)
+  );
+  if (loggerParams.length > 0) {
+    loggerParams.forEach((p) => {
+      console.log(`  ${p.key}: ${JSON.stringify(p.value)} (from ${p.source})`);
+    });
+  } else {
+    console.log("  (no parameters requested)");
+  }
+  console.log("\n=== End Parameters ===\n");
+}
+async function init(flow2, opts = {}) {
+  let stop = false;
+  let context = null;
+  try {
+    try {
+      const screenModule = await Promise.resolve().then(() => (init_screen(), screen_exports));
+      if (screenModule && typeof screenModule.load === "function") {
+        await screenModule.load();
+      }
+    } catch {
+      if (typeof __require !== "undefined") {
+        try {
+        } catch {
+        }
+      }
+    }
+    context = setup(opts);
+    context.isStop = () => stop;
+    context = await setupModules(context, opts);
+    const stopAfter = context.args.get("stopAfter");
+    const stopAllowance = context.params.get("stopAllowance", "number default 5");
+    if (stopAfter === "init") {
+      printAllParameters(context);
+      process.exit(0);
+    }
+    process.on("SIGINT", async () => {
+      if (stop) {
+        context.logger.warn("[process] killed");
+        process.exit(2);
+      }
+      stop = true;
+      context.logger.info(`>> emitting stop with allowance ${stopAllowance}`);
+      context.emitter.emit("stop", stopAllowance);
+    });
+    await flow2(context);
+  } catch (error) {
+    const errorLocation = error instanceof Error && error.stack ? error.stack.split("\n")[1]?.trim() || "Unknown location" : "Unknown location";
+    const logError = (msg, ...args) => {
+      if (context?.logger) {
+        context.logger.error(msg, ...args);
+      } else {
+        console.error(msg, ...args);
+      }
+    };
+    if (error instanceof ParamError) {
+      logError(`[params]: ${error.message} (${errorLocation})`);
+      process.exitCode = 3;
+    } else if (error instanceof InitError) {
+      logError(`[init]: ${error.message} (${errorLocation})`);
+      process.exitCode = 4;
+    } else {
+      logError(`[other] error:`, error, errorLocation);
+      process.exitCode = 5;
+    }
+  } finally {
+    if (context) {
+      for (const fn of context.cleanupFunctions.reverse()) {
+        try {
+          await fn(context);
+        } catch (error) {
+          context.logger.warn("[cleanup] error in cleanup function:", error);
+        }
+      }
+    }
+  }
+}
+
+// src/db/index.ts
+import knex from "knex";
+var Db = class {
+  knexInstance = null;
+  config;
+  logger;
+  queriesLog = [];
+  isConnected = false;
+  /**
+   * Constructor - accepts config object
+   * Use dbInit() function to initialize with Context
+   */
+  constructor(config2) {
+    if (!config2.connectionString) {
+      throw new ParamError("Db: connectionString is required");
+    }
+    this.config = {
+      testConnection: true,
+      profile: false,
+      pool: { min: 2, max: 10 },
+      acquireConnectionTimeout: 1e4,
+      ssl: { rejectUnauthorized: false },
+      logger: console,
+      name: "default",
+      ...config2
+    };
+    this.logger = this.config.logger;
+    const instance = this;
+    const callableWrapper = function(...args) {
+      throw new Error("This should never be called directly");
+    };
+    callableWrapper._instance = instance;
+    return new Proxy(callableWrapper, {
+      // Intercept function calls: db('table')
+      apply: (target, thisArg, argumentsList) => {
+        const inst = target._instance;
+        if (!inst.knexInstance) {
+          throw new Error("Db: Not connected. Call connect() first.");
+        }
+        return inst.knexInstance(...argumentsList);
+      },
+      // Intercept property access: db.schema, db.raw, etc.
+      get: (target, prop) => {
+        if (prop === "_instance") {
+          return target._instance;
+        }
+        const instance2 = target._instance;
+        const ownMethods = [
+          "connect",
+          "disconnect",
+          "testConnection",
+          "tableExists",
+          "getQueryLog",
+          "getKnex",
+          "isConnectedToDb",
+          "getErrorMessage",
+          "detectClient",
+          "attachProfiler"
+        ];
+        if (prop in instance2) {
+          const value = instance2[prop];
+          if (typeof value === "function" && ownMethods.includes(prop)) {
+            return value.bind(instance2);
+          }
+          if (typeof value !== "function") {
+            return value;
+          }
+        }
+        if (instance2.knexInstance) {
+          const knexProp = instance2.knexInstance[prop];
+          if (typeof knexProp === "function") {
+            return knexProp.bind(instance2.knexInstance);
+          }
+          return knexProp;
+        }
+        if (prop in instance2) {
+          const method = instance2[prop];
+          if (typeof method === "function") {
+            return method.bind(instance2);
+          }
+          return method;
+        }
+        return void 0;
+      }
+    });
+  }
+  /**
+   * Detect database client type from connection string
+   */
+  detectClient(connectionString) {
+    if (connectionString.match(/^postgresql/)) {
+      return "pg";
+    }
+    if (connectionString.match(/^mysql/)) {
+      return "mysql2";
+    }
+    return null;
+  }
+  /**
+   * Connect to the database
+   */
+  async connect() {
+    if (this.isConnected && this.knexInstance) {
+      this.logger.warn?.("[Db] Already connected");
+      return;
+    }
+    const client = this.detectClient(this.config.connectionString);
+    if (!client) {
+      throw new ParamError(
+        `Db: Cannot determine client type from connection string. Expected postgresql:// or mysql://`
+      );
+    }
+    try {
+      const connectionConfig = {
+        connectionString: this.config.connectionString,
+        family: 4
+        // Force IPv4 only (disable IPv6)
+      };
+      this.knexInstance = knex({
+        client,
+        connection: connectionConfig,
+        pool: this.config.pool,
+        acquireConnectionTimeout: this.config.acquireConnectionTimeout,
+        ...this.config.ssl && { ssl: this.config.ssl }
+      });
+      if (this.config.profile) {
+        this.attachProfiler();
+      }
+      if (this.config.testConnection) {
+        await this.testConnection();
+      }
+      this.isConnected = true;
+      this.logger.debug?.(`[Db] Connected to database "${this.config.name || this.config.connectionString}"`);
+    } catch (error) {
+      if (error instanceof ParamError) {
+        throw error;
+      }
+      const errorMsg = this.getErrorMessage(error);
+      throw new ParamError(`Db: Connection failed - ${errorMsg}`);
+    }
+  }
+  /**
+   * Disconnect from the database
+   */
+  async disconnect() {
+    if (!this.knexInstance) {
+      return;
+    }
+    try {
+      await this.knexInstance.destroy();
+      this.knexInstance = null;
+      this.isConnected = false;
+      this.queriesLog = [];
+      this.logger.debug?.(`[Db] Disconnected from database "${this.config.name || this.config.connectionString}"`);
+    } catch (error) {
+      const errorMsg = this.getErrorMessage(error);
+      this.logger.error?.(`[Db] Error disconnecting: ${errorMsg}`);
+      throw error;
+    }
+  }
+  /**
+   * Extract error message from various error types
+   */
+  getErrorMessage(error) {
+    if (error instanceof AggregateError) {
+      const errors = error.errors || [];
+      if (errors.length > 0) {
+        const firstError = errors[0];
+        const firstErrorMsg = firstError instanceof Error ? firstError.message : String(firstError);
+        const allSimilar = errors.every((e) => {
+          const msg = e instanceof Error ? e.message : String(e);
+          const codeMatch = msg.match(/^(\w+)\s/);
+          const firstCodeMatch = firstErrorMsg.match(/^(\w+)\s/);
+          return codeMatch && firstCodeMatch && codeMatch[1] === firstCodeMatch[1];
+        });
+        if (allSimilar && errors.length > 1) {
+          const addresses = errors.map((e) => {
+            const msg = e instanceof Error ? e.message : String(e);
+            const addrMatch = msg.match(/([:\d.]+:\d+)/);
+            return addrMatch ? addrMatch[1] : null;
+          }).filter(Boolean);
+          if (addresses.length > 0) {
+            const codeMatch = firstErrorMsg.match(/^(\w+)\s/);
+            const code = codeMatch ? codeMatch[1] : "Connection error";
+            return `${code} (tried: ${addresses.join(", ")})`;
+          }
+        }
+        const uniqueMessages = [...new Set(errors.map((e) => {
+          return e instanceof Error ? e.message : String(e);
+        }))];
+        if (uniqueMessages.length === 1) {
+          return uniqueMessages[0];
+        }
+        return uniqueMessages.join("; ");
+      }
+      return error.message || "Multiple errors occurred";
+    }
+    if (error instanceof Error) {
+      const errorWithCode = error;
+      if (errorWithCode.code) {
+        return `${errorWithCode.code}: ${error.message || String(error)}`;
+      }
+      return error.message || String(error);
+    }
+    if (typeof error === "string") {
+      return error;
+    }
+    if (error?.message) {
+      const msg = String(error.message);
+      const errorWithCode = error;
+      if (errorWithCode.code) {
+        return `${errorWithCode.code}: ${msg}`;
+      }
+      return msg;
+    }
+    return String(error) || "Unknown error";
+  }
+  /**
+   * Test database connection
+   */
+  async testConnection() {
+    if (!this.knexInstance) {
+      throw new Error("Db: Not connected. Call connect() first.");
+    }
+    try {
+      const result = await this.knexInstance.raw("SELECT 2+3 AS result");
+      const isOk = result.rows?.[0]?.result === 5 || result[0]?.[0]?.result === 5;
+      this.logger.debug?.(`[Db] Connection test: ${isOk ? "OK" : "FAILED"}`);
+      return isOk;
+    } catch (error) {
+      const errorMsg = this.getErrorMessage(error);
+      this.logger.error?.(`[Db] Connection test failed: ${errorMsg}`);
+      throw new ParamError(`Db: Connection test failed - ${errorMsg}`);
+    }
+  }
+  /**
+   * Attach query profiler to log all queries
+   */
+  attachProfiler() {
+    if (!this.knexInstance) {
+      return;
+    }
+    this.queriesLog = [];
+    this.knexInstance.queriesLog = this.queriesLog;
+    this.knexInstance.on("query", (query) => {
+      query.__startTime = process.hrtime();
+    });
+    this.knexInstance.on("query-response", (response, query) => {
+      const [seconds, nanoseconds] = process.hrtime(query.__startTime);
+      const executionTimeMs = (seconds * 1e3 + nanoseconds / 1e6).toFixed(2);
+      const logEntry = {
+        sql: query.sql,
+        bindings: query.bindings || [],
+        executionTimeMs
+      };
+      this.queriesLog.push(logEntry);
+      this.logger.debug?.(`[Db] Query: ${query.sql} | Duration: ${executionTimeMs}ms`);
+    });
+    this.knexInstance.on("query-error", (error, query) => {
+      this.logger.error?.(`[Db] Query failed: ${query.sql}`, error);
+    });
+  }
+  /**
+   * Get query log (only available if profiling is enabled)
+   */
+  getQueryLog() {
+    return [...this.queriesLog];
+  }
+  /**
+   * Check if a table exists
+   */
+  async tableExists(tableName) {
+    if (!this.knexInstance) {
+      throw new Error("Db: Not connected. Call connect() first.");
+    }
+    try {
+      return await this.knexInstance.schema.hasTable(tableName);
+    } catch (error) {
+      this.logger.error?.(`[Db] Error checking table existence: ${error.message}`);
+      throw error;
+    }
+  }
+  /**
+   * Get the underlying Knex instance (for advanced usage)
+   */
+  getKnex() {
+    if (!this.knexInstance) {
+      throw new Error("Db: Not connected. Call connect() first.");
+    }
+    return this.knexInstance;
+  }
+  /**
+   * Get connection status
+   */
+  isConnectedToDb() {
+    return this.isConnected && this.knexInstance !== null;
+  }
+  /**
+   * Initialize Db with context (connects and registers disconnect cleanup).
+   * Params are read via getAllForModule("db", defs). Same as dbInit(context, dbNameOrConnectionString).
+   */
+  static async init(context, dbNameOrConnectionString) {
+    return dbFindAndConnect(context, dbNameOrConnectionString);
+  }
+};
+function capitalizeFirstLetter(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+async function dbConnect(context, connectionString, name, dbProfile) {
+  const defs2 = {
+    testDbConnection: "boolean default true",
+    name: "string",
+    poolMin: "number default 2",
+    poolMax: "number default 10",
+    acquireConnectionTimeout: "number default 10000",
+    sslRejectUnauthorized: "boolean default false"
+  };
+  const paramsConfig = context.params.getAllForModule(defs2);
+  const config2 = {
+    connectionString,
+    name: paramsConfig.name || name || "default",
+    testConnection: paramsConfig.testDbConnection,
+    profile: dbProfile ?? false,
+    pool: {
+      min: paramsConfig.poolMin,
+      max: paramsConfig.poolMax
+    },
+    acquireConnectionTimeout: paramsConfig.acquireConnectionTimeout,
+    ssl: {
+      rejectUnauthorized: paramsConfig.sslRejectUnauthorized
+    },
+    logger: context.logger
+  };
+  try {
+    const db = new Db(config2);
+    context.registerCleanup(async () => {
+      await db.disconnect();
+      context.logger.debug(`[Db] instance "${name || connectionString}" destroyed`);
+    });
+    await db.connect();
+    context.logger.debug(`[Db] instance "${name || connectionString}" initialized`);
+    return db;
+  } catch (error) {
+    if (error instanceof ParamError) {
+      throw error;
+    }
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    throw new ParamError(`[Db] connect error: ${errorMsg}`);
+  }
+}
+async function dbFindAndConnect(context, dbNameOrConnectionString) {
+  let dbName;
+  let dbConnectionString;
+  let dbProfile;
+  if (dbNameOrConnectionString) {
+    if (dbNameOrConnectionString.match(/^(postgresql|mysql):\/\/[^\s]+:[^\s]+@[^\s]+:\d+\/[^\s]+$/)) {
+      dbName = void 0;
+      dbConnectionString = dbNameOrConnectionString;
+    } else {
+      dbName = dbNameOrConnectionString;
+    }
+  } else {
+    const defs2 = {
+      dbName: "string",
+      dbConnectionString: "string",
+      dbProfile: "boolean default false"
+    };
+    const paramsConfig = context.params.getAllForModule(defs2);
+    dbName = paramsConfig.dbName;
+    dbConnectionString = paramsConfig.dbConnectionString;
+    dbProfile = paramsConfig.dbProfile;
+  }
+  if (!dbName && !dbConnectionString) {
+    throw new ParamError("Db: either dbName or dbConnectionString must be specified");
+  }
+  if (dbName) {
+    const paramName = `dbConnectionString${capitalizeFirstLetter(dbName)}`;
+    dbConnectionString = await context.params.get(paramName, "string");
+    if (!dbConnectionString) {
+      throw new ParamError(
+        `Db: cannot find dbConnectionString for dbName="${dbName}" (looked for param "${paramName}")`
+      );
+    }
+  }
+  const db = await dbConnect(context, dbConnectionString, dbName, dbProfile);
+  return db;
+}
+async function dbInit(context, dbNameOrConnectionString) {
+  return await dbFindAndConnect(context, dbNameOrConnectionString);
+}
+
+// src/utils/date-utils.ts
+function isTimestampFolder(folderName) {
+  const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|\.\d{3}Z)$/;
+  if (!isoRegex.test(folderName)) {
+    return false;
+  }
+  const date = new Date(folderName);
+  return !isNaN(date.getTime()) && date.getTime() > 0;
+}
+
+// src/utils/fs-utils.ts
+import fs from "fs";
+import path from "path";
+async function ensurePath(...pathParts) {
+  const fullPath = path.resolve(...pathParts);
+  if (!fs.existsSync(fullPath)) {
+    await fs.promises.mkdir(fullPath, { recursive: true });
+  }
+  return fullPath;
+}
+function getFileExtension(dataType) {
+  switch (dataType) {
+    case "json-array":
+    case "json-object":
+      return "json";
+    case "text":
+      return "txt";
+    case "xml":
+      return "xml";
+    default:
+      return "json";
+  }
+}
+
+// src/utils/os-utils.ts
+import fs2 from "fs";
+import path2 from "path";
+import { execSync } from "child_process";
+function getFreeDiskSpace(targetPath) {
+  try {
+    let pathToCheck = targetPath;
+    if (!fs2.existsSync(targetPath)) {
+      const parentDir = path2.dirname(targetPath);
+      if (fs2.existsSync(parentDir)) {
+        pathToCheck = parentDir;
+      } else {
+        pathToCheck = process.platform === "win32" ? "C:\\" : "/";
+      }
+    }
+    if (process.platform === "win32") {
+      return null;
+    } else {
+      const stdout = execSync(`df -k "${pathToCheck}"`, { encoding: "utf8" });
+      const lines = stdout.trim().split("\n");
+      const parts = lines[1].split(/\s+/);
+      const freeKb = parseInt(parts[3], 10);
+      return freeKb * 1024;
+    }
+  } catch (error) {
+    return null;
+  }
+}
+
+// src/utils/format-utils.ts
+function bytesToHumanReadable(bytes) {
+  if (bytes === 0) return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB", "PB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+}
+
+// src/utils/core-utils.ts
+function sleepMs(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function toJsonColumn(value) {
+  if (value === void 0 || value === null) return null;
+  return JSON.stringify(value);
+}
+
+// src/tasks/taskUtils.ts
+import { randomUUID } from "crypto";
+function getDb(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Tasks component requires context.db. Initialize DB first and attach to context.");
+  }
+  return db;
+}
+function queueToTableNames(queue) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(queue)) {
+    throw new Error(`Invalid queue name "${queue}". Use letters, numbers, underscore only.`);
+  }
+  return {
+    tasksTable: queue,
+    historyTable: `${queue}_history`
+  };
+}
+async function ensureTaskTables(context, options = {}) {
+  const queue = options.queue ?? "tasks";
+  const recreate = options.recreate ?? false;
+  const db = getDb(context);
+  const { tasksTable, historyTable } = queueToTableNames(queue);
+  const needsTasks = recreate ? true : !await db.tableExists(tasksTable);
+  const needsHistory = recreate ? true : !await db.tableExists(historyTable);
+  if (recreate) {
+    await db.schema.dropTableIfExists(historyTable);
+    await db.schema.dropTableIfExists(tasksTable);
+  }
+  if (needsTasks) {
+    await db.raw(`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`);
+    await db.schema.createTable(tasksTable, (t) => {
+      t.uuid("id").primary().defaultTo(db.raw("uuid_generate_v4()"));
+      t.timestamp("created_at").notNullable().defaultTo(db.fn.now());
+      t.timestamp("started_at");
+      t.timestamp("completed_at");
+      t.integer("priority").notNullable().defaultTo(0);
+      t.text("schedule");
+      t.timestamp("past_due").defaultTo(null);
+      t.text("target").notNullable();
+      t.text("task").notNullable();
+      t.json("params");
+      t.text("opid");
+      t.timestamp("paused_at").defaultTo(null);
+      t.text("progress");
+      t.boolean("success");
+      t.json("results");
+    });
+    await db.schema.alterTable(tasksTable, (t) => {
+      t.index(["target", "started_at", "created_at"], `${tasksTable}_target_started_created_idx`);
+      t.index(["target", "past_due", "priority", "created_at"], `${tasksTable}_target_past_due_priority_created_idx`);
+      t.index(["target", "task"], `${tasksTable}_target_task_idx`);
+    });
+  }
+  const tasksHasOpid = await db.schema.hasColumn(tasksTable, "opid");
+  if (!tasksHasOpid) {
+    await db.schema.alterTable(tasksTable, (t) => {
+      t.text("opid");
+    });
+  }
+  const tasksHasPausedAt = await db.schema.hasColumn(tasksTable, "paused_at");
+  if (!tasksHasPausedAt) {
+    await db.schema.alterTable(tasksTable, (t) => {
+      t.timestamp("paused_at").defaultTo(null);
+    });
+  }
+  if (needsHistory) {
+    await db.schema.createTable(historyTable, (t) => {
+      t.uuid("id").notNullable();
+      t.timestamp("created_at").notNullable();
+      t.timestamp("started_at");
+      t.timestamp("completed_at");
+      t.integer("priority").notNullable().defaultTo(0);
+      t.text("schedule");
+      t.timestamp("past_due").defaultTo(null);
+      t.text("target").notNullable();
+      t.text("task").notNullable();
+      t.json("params");
+      t.text("opid");
+      t.text("progress");
+      t.boolean("success");
+      t.json("results");
+    });
+    await db.schema.alterTable(historyTable, (t) => {
+      t.index(["target", "created_at"], `${historyTable}_target_created_idx`);
+      t.index(["task", "created_at"], `${historyTable}_task_created_idx`);
+    });
+  }
+  const historyHasOpid = await db.schema.hasColumn(historyTable, "opid");
+  if (!historyHasOpid) {
+    await db.schema.alterTable(historyTable, (t) => {
+      t.text("opid");
+    });
+  }
+}
+async function updateTaskProgress(context, tasksTable, taskId, progress) {
+  const db = getDb(context);
+  await db(tasksTable).where({ id: taskId }).update({
+    progress: typeof progress === "string" ? progress : JSON.stringify(progress)
+  });
+}
+
+// src/filedatabase/index.ts
+import fs3 from "fs";
+import path3 from "path";
+
+// src/filedatabase/serializers.ts
+function detectDataType(data) {
+  if (Array.isArray(data)) {
+    return "json-array";
+  } else if (typeof data === "object" && data !== null) {
+    return "json-object";
+  } else if (typeof data === "string") {
+    const trimmed = data.trim();
+    if (trimmed.startsWith("<?xml") || trimmed.startsWith("<")) {
+      return "xml";
+    }
+    return "text";
+  } else {
+    return "text";
+  }
+}
+function serializeData(data) {
+  const dataType = detectDataType(data);
+  if (dataType === "json-array" || dataType === "json-object") {
+    return JSON.stringify(data, null, 4);
+  } else {
+    return String(data);
+  }
+}
+function deserializeData(rawData, dataType) {
+  if (dataType === "json-array" || dataType === "json-object") {
+    return JSON.parse(rawData);
+  } else {
+    return rawData;
+  }
+}
+
+// src/filedatabase/index.ts
+var FileDatabase = class _FileDatabase {
+  basePath;
+  namespace;
+  tableName = null;
+  versioned;
+  maxVersions;
+  pageSize;
+  useMetadata;
+  freeSpaceThreshold;
+  logger;
+  // Current operation state
+  currentVersion = null;
+  currentVersionFolder = null;
+  currentFileNumber = 0;
+  currentRecord = 0;
+  hasReadFirstPage = false;
+  lastFileData = null;
+  metadata;
+  // Synopsis calculation functions
+  fileSynopsisFunction = null;
+  versionSynopsisFunction = null;
+  /**
+   * Constructor - accepts context as first parameter (new pattern)
+   * or config object (legacy pattern for backward compatibility)
+   */
+  constructor(contextOrConfig, options) {
+    let config2;
+    if (contextOrConfig && typeof contextOrConfig === "object" && "params" in contextOrConfig) {
+      const context = contextOrConfig;
+      const opts = options || {};
+      const defs2 = {
+        basePath: "string default ./data",
+        namespace: "string default default",
+        tableName: "string",
+        maxVersions: "number default 5",
+        pageSize: "number default 5000"
+      };
+      const discovered = context.params.getAllForModule(defs2);
+      config2 = { ...discovered, ...opts, logger: context.logger };
+    } else {
+      config2 = contextOrConfig;
+    }
+    if (!config2.basePath) {
+      throw new ParamError("[FileDatabase] basePath is required");
+    }
+    this.basePath = config2.basePath;
+    this.namespace = config2.namespace || "default";
+    this.tableName = config2.tableName || null;
+    this.versioned = config2.versioned ?? true;
+    this.maxVersions = config2.maxVersions || 5;
+    this.pageSize = config2.pageSize || 5e3;
+    this.useMetadata = config2.useMetadata !== false;
+    this.freeSpaceThreshold = config2.freeSpaceThreshold || 100 * 1024 * 1024;
+    this.logger = config2.logger || console;
+    this.metadata = this.getDefaultMetadata();
+  }
+  /**
+   * Initialize FileDatabase from context and options.
+   * Params are read via getAllForModule("filedatabase", defs) for --showUsedParams grouping.
+   */
+  static init(context, options) {
+    return new _FileDatabase(context, options ?? {});
+  }
+  /**
+   * Get default metadata structure
+   */
+  getDefaultMetadata() {
+    return {
+      version: this.currentVersion || null,
+      files: [],
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      modifiedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      totalRecords: 0,
+      synopsis: null,
+      dataType: null
+    };
+  }
+  /**
+   * Get the destination path (basePath/namespace/tableName[/version])
+   */
+  getDestinationPath(version) {
+    const errors = ["basePath", "namespace", "tableName"].filter((prop) => !this[prop]).map((prop) => `${prop} is not set`);
+    if (errors.length) {
+      throw new FileDatabaseError(`[FileDatabase] ${errors.join("; ")}`);
+    }
+    let parts = [this.basePath, this.namespace];
+    if (this.tableName) {
+      parts.push(...this.tableName.split("/"));
+    }
+    if (this.versioned && version) {
+      parts.push(version);
+    }
+    return path3.resolve(...parts);
+  }
+  /**
+   * Set current version and version folder
+   */
+  async setCurrentVersion(version) {
+    this.currentVersion = version;
+    this.currentVersionFolder = await ensurePath(this.getDestinationPath(), version);
+  }
+  /**
+   * Create a new version folder with comprehensive timestamp logic
+   * Only works in versioned mode
+   */
+  async makeNewVersion() {
+    if (!this.versioned) {
+      throw new FileDatabaseError("makeNewVersion() only works in versioned mode");
+    }
+    this.metadata = this.getDefaultMetadata();
+    const existingVersions = await this.getVersions();
+    let versionName;
+    if (existingVersions.length > 0) {
+      const maxTimestamp = existingVersions.reduce((max, version) => {
+        const versionDate = new Date(version.replace("Z", ""));
+        const maxDate2 = new Date(max.replace("Z", ""));
+        return versionDate > maxDate2 ? version : max;
+      });
+      const maxDate = new Date(maxTimestamp.replace("Z", ""));
+      const nextDate = new Date(maxDate.getTime() + 1e3);
+      versionName = nextDate.toISOString().split(".")[0] + "Z";
+    } else {
+      const now = /* @__PURE__ */ new Date();
+      versionName = now.toISOString().split(".")[0] + "Z";
+    }
+    await this.setCurrentVersion(versionName);
+    this.currentFileNumber = 0;
+    const versions = await this.getVersions();
+    while (versions.length > this.maxVersions) {
+      const versionToDelete = path3.resolve(this.getDestinationPath(), versions.shift());
+      this.logger.silly?.(`[FileDatabase] Deleting old version: ${versionToDelete}`);
+      await fs3.promises.rm(versionToDelete, { recursive: true, force: true });
+    }
+    return versionName;
+  }
+  /**
+   * Get list of all versions (sorted chronologically)
+   * Only works in versioned mode
+   */
+  async getVersions() {
+    if (!this.versioned) {
+      return [];
+    }
+    const destPath = this.getDestinationPath();
+    try {
+      await ensurePath(destPath);
+      const items = await fs3.promises.readdir(destPath);
+      const versions = items.filter((item) => {
+        const itemPath = path3.join(destPath, item);
+        const stat = fs3.statSync(itemPath);
+        return stat.isDirectory() && isTimestampFolder(item);
+      });
+      return versions.sort();
+    } catch (error) {
+      return [];
+    }
+  }
+  /**
+   * Get the latest version (most recent timestamp)
+   * Only works in versioned mode
+   * @returns Latest version string or null if no versions
+   */
+  async getLatestVersion() {
+    if (!this.versioned) {
+      throw new FileDatabaseError("getLatestVersion() only works in versioned mode");
+    }
+    const versions = await this.getVersions();
+    if (versions.length === 0) {
+      return null;
+    }
+    return versions[versions.length - 1];
+  }
+  /**
+   * Check if any data exists in this table
+   * Works for both versioned and non-versioned modes
+   * @returns true if data exists
+   */
+  async hasData() {
+    const tablePath = this.getDestinationPath();
+    if (!fs3.existsSync(tablePath)) {
+      return false;
+    }
+    if (this.versioned) {
+      const versions = await this.getVersions();
+      return versions.length > 0;
+    } else {
+      const items = await fs3.promises.readdir(tablePath);
+      return items.some(
+        (item) => item === "metadata.json" || item.match(/^\d{6}\.(json|txt|xml)$/) || item.endsWith(".json")
+      );
+    }
+  }
+  /**
+   * Auto-detect the data format in this table
+   * Used when reading existing data
+   * @returns Format detection result
+   */
+  async detectDataFormat() {
+    const tablePath = this.getDestinationPath();
+    if (!fs3.existsSync(tablePath)) {
+      return { versioned: false, hasMetadata: false, dataType: null };
+    }
+    const items = await fs3.promises.readdir(tablePath);
+    if (items.includes("metadata.json")) {
+      const metadata = JSON.parse(
+        await fs3.promises.readFile(path3.join(tablePath, "metadata.json"), "utf8")
+      );
+      return {
+        versioned: false,
+        hasMetadata: true,
+        dataType: metadata.dataType || null
+      };
+    }
+    const versionFolders = items.filter((item) => {
+      const itemPath = path3.join(tablePath, item);
+      const stat = fs3.statSync(itemPath);
+      return stat.isDirectory() && isTimestampFolder(item);
+    });
+    if (versionFolders.length > 0) {
+      const latestVersion = versionFolders.sort().pop();
+      const versionMetadataPath = path3.join(tablePath, latestVersion, "metadata.json");
+      return {
+        versioned: true,
+        hasMetadata: fs3.existsSync(versionMetadataPath),
+        dataType: null
+      };
+    }
+    const dataFiles = items.filter((f) => f.match(/^\d{6}\.(json|txt|xml)$/));
+    if (dataFiles.length > 0) {
+      return {
+        versioned: false,
+        hasMetadata: false,
+        dataType: null
+      };
+    }
+    return { versioned: false, hasMetadata: false, dataType: null };
+  }
+  /**
+   * Load metadata from JSON file
+   */
+  async loadMetadataJson(version) {
+    const metadataFile = path3.join(this.getDestinationPath(), version, "metadata.json");
+    if (fs3.existsSync(metadataFile)) {
+      try {
+        const rawData = await fs3.promises.readFile(metadataFile, "utf8");
+        return JSON.parse(rawData);
+      } catch (e) {
+        throw new FileDatabaseError(`Failed to read metadata for version "${version}": ${e.message}`);
+      }
+    }
+    return null;
+  }
+  /**
+   * Build metadata by scanning files in a version folder (backward compatibility)
+   * Reads all files to get accurate counts - used when synopsis calculation is needed
+   */
+  async figureMetadataFromVersionFiles(version) {
+    const versionPath = path3.join(this.getDestinationPath(), version);
+    if (!fs3.existsSync(versionPath)) {
+      return this.getDefaultMetadata();
+    }
+    const files = (await fs3.promises.readdir(versionPath)).filter((file) => file !== "metadata.json" && !file.startsWith(".")).sort();
+    const metadata = this.getDefaultMetadata();
+    metadata.version = version;
+    metadata.files = [];
+    let totalRecords = 0;
+    let detectedDataType = null;
+    for (let i = 0; i < files.length; i++) {
+      const fileName = files[i];
+      const filePath = path3.join(versionPath, fileName);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        const extension = path3.extname(fileName).toLowerCase();
+        let dataType = "text";
+        if (extension === ".json") {
+          dataType = "json-array";
+        } else if (extension === ".xml") {
+          dataType = "xml";
+        }
+        const fileData = deserializeData(rawData, dataType);
+        const recordsCount = Array.isArray(fileData) ? fileData.length : 1;
+        if (detectedDataType === null) {
+          detectedDataType = detectDataType(fileData);
+        }
+        const fileInfo = {
+          number: i + 1,
+          recordsCount,
+          fileName
+        };
+        metadata.files.push(fileInfo);
+        totalRecords += recordsCount;
+      } catch (error) {
+        this.logger.error?.(`[FileDatabase] Failed to read file ${fileName}: ${error.message}`);
+      }
+    }
+    metadata.totalRecords = totalRecords;
+    metadata.dataType = detectedDataType;
+    return metadata;
+  }
+  /**
+   * Build metadata optimized - only reads first and last files
+   * Assumes all middle files have the same record count as the first file
+   * Much faster for large datasets with many files
+   */
+  async buildMetadataOptimized(version) {
+    const versionPath = path3.join(this.getDestinationPath(), version);
+    if (!fs3.existsSync(versionPath)) {
+      return this.getDefaultMetadata();
+    }
+    const files = (await fs3.promises.readdir(versionPath)).filter((file) => file !== "metadata.json" && !file.startsWith(".")).sort();
+    if (files.length === 0) {
+      return this.getDefaultMetadata();
+    }
+    const metadata = this.getDefaultMetadata();
+    metadata.version = version;
+    metadata.files = files.map((fileName, index) => ({
+      number: index + 1,
+      recordsCount: 0,
+      fileName
+    }));
+    const firstFile = metadata.files[0];
+    const firstFilePath = path3.join(versionPath, firstFile.fileName);
+    const firstFileRaw = await fs3.promises.readFile(firstFilePath, "utf8");
+    let firstFileData;
+    try {
+      firstFileData = JSON.parse(firstFileRaw);
+    } catch (e) {
+      firstFileData = firstFileRaw;
+    }
+    metadata.dataType = detectDataType(firstFileData);
+    if (metadata.dataType === "json-array") {
+      const firstFileCount = Array.isArray(firstFileData) ? firstFileData.length : 1;
+      firstFile.recordsCount = firstFileCount;
+      for (let i = 1; i < metadata.files.length - 1; i++) {
+        metadata.files[i].recordsCount = firstFileCount;
+      }
+      if (files.length > 1) {
+        const lastFile = metadata.files[metadata.files.length - 1];
+        const lastFilePath = path3.join(versionPath, lastFile.fileName);
+        const lastFileRaw = await fs3.promises.readFile(lastFilePath, "utf8");
+        const lastFileData = deserializeData(lastFileRaw, metadata.dataType);
+        lastFile.recordsCount = Array.isArray(lastFileData) ? lastFileData.length : 1;
+      }
+      metadata.totalRecords = metadata.files.reduce((sum, file) => sum + file.recordsCount, 0);
+    } else {
+      metadata.files.forEach((file) => {
+        file.recordsCount = 1;
+      });
+      metadata.totalRecords = files.length;
+    }
+    return metadata;
+  }
+  /**
+   * Figure out metadata - tries JSON first, then builds from files
+   * Uses optimized building when no synopsis calculation is needed
+   */
+  async figureMetadata(version, useOptimized = true) {
+    if (this.useMetadata) {
+      const metadata = await this.loadMetadataJson(version);
+      if (metadata) {
+        return metadata;
+      }
+    }
+    if (useOptimized && !this.fileSynopsisFunction && !this.versionSynopsisFunction) {
+      return await this.buildMetadataOptimized(version);
+    }
+    return await this.figureMetadataFromVersionFiles(version);
+  }
+  /**
+   * Load version metadata (main entry point for loading)
+   */
+  async loadVersionMetadata(version) {
+    const metadata = await this.figureMetadata(version);
+    this.metadata = metadata;
+    return metadata;
+  }
+  /**
+   * Save version metadata to file
+   */
+  async saveVersionMetadata(metadata) {
+    if (!this.useMetadata) {
+      return;
+    }
+    const metadataToSave = metadata || this.metadata;
+    let metadataFile;
+    if (this.versioned) {
+      if (!this.currentVersion) {
+        return;
+      }
+      metadataFile = path3.join(this.getDestinationPath(), this.currentVersion, "metadata.json");
+    } else {
+      metadataFile = path3.join(this.getDestinationPath(), "metadata.json");
+    }
+    await fs3.promises.writeFile(metadataFile, JSON.stringify(metadataToSave, null, 4), "utf8");
+  }
+  /**
+   * Create a new file entry in metadata
+   */
+  makeNewFile() {
+    this.currentFileNumber = (this.currentFileNumber || 0) + 1;
+    const dataType = this.metadata.dataType || "json-array";
+    const fileEntry = {
+      number: this.currentFileNumber,
+      recordsCount: 0,
+      fileName: `${this.currentFileNumber.toString().padStart(6, "0")}.${getFileExtension(dataType)}`
+    };
+    this.metadata.files.push(fileEntry);
+    this.lastFileData = null;
+    this.logger.silly?.(`[FileDatabase] Created new file: ${fileEntry.fileName}, fileNumber: ${this.currentFileNumber}`);
+  }
+  /**
+   * Figure out what data to write and which file to use (for pagination)
+   * @param data - Data to write
+   * @param targetFileIndex - Optional index of existing file to overwrite (when customMetadata matches)
+   * @param forceNewFile - If true, always create a new file (when customMetadata provided but no match)
+   */
+  figureOutDataAndFileToWrite(data, targetFileIndex = null, forceNewFile = false) {
+    let dataToWrite;
+    let dataLeftOver;
+    const incomingDataType = detectDataType(data);
+    if (this.metadata.dataType !== incomingDataType) {
+      this.metadata.dataType = incomingDataType;
+    }
+    if (targetFileIndex !== null && targetFileIndex < this.metadata.files.length) {
+      const targetFile = this.metadata.files[targetFileIndex];
+      if (!Array.isArray(data)) {
+        dataToWrite = data;
+        dataLeftOver = null;
+        return { dataToWrite, dataLeftOver, fileName: targetFile.fileName };
+      } else {
+        dataToWrite = data.slice(0, this.pageSize);
+        dataLeftOver = data.slice(this.pageSize);
+        this.lastFileData = dataToWrite;
+        return { dataToWrite, dataLeftOver, fileName: targetFile.fileName };
+      }
+    }
+    let newlyCreatedFileIndex = null;
+    if (forceNewFile) {
+      const filesBeforeCreate = this.metadata.files.length;
+      this.makeNewFile();
+      newlyCreatedFileIndex = filesBeforeCreate;
+      this.logger.silly?.(`[FileDatabase] Creating new file for unique custom metadata combination, fileNumber: ${this.currentFileNumber}`);
+    } else if (this.metadata.files.length === 0) {
+      this.makeNewFile();
+    }
+    const lastFile = this.metadata.files[this.metadata.files.length - 1];
+    const lastFileRecordsCount = lastFile.recordsCount;
+    if (forceNewFile && newlyCreatedFileIndex !== null) {
+      const newlyCreatedFile = this.metadata.files[newlyCreatedFileIndex];
+      if (newlyCreatedFile && newlyCreatedFile.fileName !== lastFile.fileName) {
+        this.logger.warn?.(`[FileDatabase] Warning: Newly created file ${newlyCreatedFile.fileName} doesn't match last file ${lastFile.fileName}`);
+      }
+    }
+    if (!Array.isArray(data) && !forceNewFile) {
+      const lastFileExtension = path3.extname(lastFile.fileName);
+      const expectedExtension = `.${getFileExtension(incomingDataType)}`;
+      if (lastFileExtension !== expectedExtension) {
+        if (lastFileRecordsCount > 0) {
+          this.makeNewFile();
+        } else {
+          lastFile.fileName = `${this.currentFileNumber.toString().padStart(6, "0")}.${getFileExtension(incomingDataType)}`;
+        }
+      }
+    } else if (!Array.isArray(data) && forceNewFile) {
+      const lastFileExtension = path3.extname(lastFile.fileName);
+      const expectedExtension = `.${getFileExtension(incomingDataType)}`;
+      if (lastFileExtension !== expectedExtension) {
+        lastFile.fileName = `${this.currentFileNumber.toString().padStart(6, "0")}.${getFileExtension(incomingDataType)}`;
+      }
+    }
+    if (Array.isArray(data)) {
+      if (forceNewFile) {
+        dataToWrite = data.slice(0, this.pageSize);
+        dataLeftOver = data.slice(this.pageSize);
+        this.lastFileData = dataToWrite;
+      } else if (lastFileRecordsCount < this.pageSize) {
+        dataToWrite = [...this.lastFileData || [], ...data.slice(0, this.pageSize - lastFileRecordsCount)];
+        dataLeftOver = data.slice(this.pageSize - lastFileRecordsCount);
+        this.lastFileData = dataToWrite;
+      } else {
+        this.makeNewFile();
+        dataToWrite = data.slice(0, this.pageSize);
+        dataLeftOver = data.slice(this.pageSize);
+        this.lastFileData = dataToWrite;
+      }
+    } else {
+      dataToWrite = data;
+      dataLeftOver = null;
+    }
+    const fileName = this.metadata.files[this.metadata.files.length - 1].fileName;
+    this.logger.silly?.(
+      `[FileDatabase] figureOutDataAndFileToWrite: filename=${fileName}, forceNewFile=${forceNewFile}, targetFileIndex=${targetFileIndex}, dataToWrite.length=${Array.isArray(dataToWrite) ? dataToWrite.length : "N/A"}, lastFileRecordsCount=${lastFileRecordsCount}`
+    );
+    return { dataToWrite, dataLeftOver, fileName };
+  }
+  /**
+   * Calculate file-level synopsis if function is set
+   */
+  calculateFileSynopsis(data, fileIndex = this.metadata.files.length - 1) {
+    if (!this.fileSynopsisFunction) {
+      return;
+    }
+    const fileInfo = this.metadata.files[fileIndex];
+    const enhancedFileInfo = this.fileSynopsisFunction(fileInfo, data);
+    this.metadata.files[fileIndex] = enhancedFileInfo;
+  }
+  /**
+   * Calculate version-level synopsis if function is set
+   */
+  calculateVersionSynopsis() {
+    if (!this.versionSynopsisFunction) {
+      return;
+    }
+    const enhancedMetadata = this.versionSynopsisFunction(this.metadata);
+    this.metadata = enhancedMetadata;
+  }
+  /**
+   * Update metadata after writing data
+   */
+  updateMetadata(dataToWrite, fileName, customMetadata) {
+    let currentFile;
+    if (fileName) {
+      const foundFile = this.metadata.files.find((file) => file.fileName === fileName);
+      if (!foundFile) {
+        this.logger.warn?.(`[FileDatabase] File ${fileName} not found in metadata, using last file`);
+        currentFile = this.metadata.files[this.metadata.files.length - 1];
+      } else {
+        currentFile = foundFile;
+      }
+    } else {
+      currentFile = this.metadata.files[this.metadata.files.length - 1];
+    }
+    const recordsCount = Array.isArray(dataToWrite) ? dataToWrite.length : 1;
+    currentFile.recordsCount = recordsCount;
+    if (customMetadata) {
+      Object.assign(currentFile, customMetadata);
+    }
+    const fileIndex = this.metadata.files.indexOf(currentFile);
+    if (fileIndex !== -1) {
+      this.calculateFileSynopsis(dataToWrite, fileIndex);
+    }
+    this.metadata.version = this.currentVersion;
+    this.metadata.modifiedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.metadata.dataType = detectDataType(dataToWrite);
+    this.metadata.totalRecords = this.metadata.files.reduce((sum, file) => sum + (file.recordsCount || 0), 0);
+    this.logger.silly?.(
+      `[FileDatabase] Updated metadata for file ${currentFile.fileName}: recordsCount=${recordsCount}, totalRecords=${this.metadata.totalRecords}`
+    );
+  }
+  /**
+   * Safe write with disk space check
+   */
+  async safeWrite(filePath, data) {
+    const serializedData = serializeData(data);
+    const dir = path3.dirname(filePath);
+    const requiredBytes = Buffer.byteLength(serializedData, "utf8");
+    const freeBytes = getFreeDiskSpace(dir);
+    if (freeBytes !== null) {
+      if (freeBytes < requiredBytes) {
+        throw new FileDatabaseError(
+          `Not enough disk space. Required: ${bytesToHumanReadable(requiredBytes)}, Free: ${bytesToHumanReadable(freeBytes)}`
+        );
+      }
+      if (freeBytes < this.freeSpaceThreshold) {
+        this.logger.warn?.(`Low disk space warning: only ${bytesToHumanReadable(freeBytes)} left`);
+      }
+    }
+    try {
+      await fs3.promises.writeFile(filePath, serializedData, "utf8");
+      this.logger.silly?.(`[FileDatabase] Wrote ${bytesToHumanReadable(requiredBytes)} to ${filePath}`);
+    } catch (error) {
+      throw new FileDatabaseError(`Failed to write file ${filePath}: ${error.message}`);
+    }
+  }
+  /**
+   * Prepare the instance for read or write operations
+   * This discovers state and sets up internal members based on mode and current data
+   */
+  async prepare({ write, read, version }) {
+    if (write) {
+      if (this.versioned) {
+        if (this.currentVersion === null) {
+          await this.makeNewVersion();
+          this.metadata = this.getDefaultMetadata();
+          this.metadata.version = this.currentVersion;
+          this.makeNewFile();
+        } else {
+          if (!this.metadata.files.length) {
+            this.metadata = await this.figureMetadata(this.currentVersion);
+            if (this.metadata.files && this.metadata.files.length > 0) {
+              this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+            } else {
+              this.currentFileNumber = 0;
+            }
+          }
+        }
+      } else {
+        await ensurePath(this.getDestinationPath());
+        if (this.useMetadata === true) {
+          const metadataPath = path3.join(this.getDestinationPath(), "metadata.json");
+          if (fs3.existsSync(metadataPath)) {
+            try {
+              const rawData = await fs3.promises.readFile(metadataPath, "utf8");
+              this.metadata = JSON.parse(rawData);
+              if (this.metadata.files && this.metadata.files.length > 0) {
+                this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+              } else {
+                this.currentFileNumber = 0;
+              }
+            } catch (e) {
+              this.metadata = this.getDefaultMetadata();
+              this.currentFileNumber = 0;
+            }
+          } else {
+            this.metadata = this.getDefaultMetadata();
+            this.currentFileNumber = 0;
+          }
+        } else {
+          this.metadata = this.getDefaultMetadata();
+          this.currentFileNumber = 0;
+        }
+      }
+    } else if (read) {
+      if (this.versioned) {
+        const versions = await this.getVersions();
+        if (versions.length === 0) {
+          throw new FileDatabaseError("[FileDatabase] No versions found, cannot read");
+        }
+        if (version) {
+          if (!versions.includes(version)) {
+            throw new FileDatabaseError(`[FileDatabase] Version "${version}" not found`);
+          }
+          await this.setCurrentVersion(version);
+        } else {
+          await this.setCurrentVersion(versions[versions.length - 1]);
+        }
+        if (!this.metadata.files.length) {
+          this.metadata = await this.figureMetadata(this.currentVersion);
+          if (this.metadata.files && this.metadata.files.length > 0) {
+            this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+          } else {
+            this.currentFileNumber = 0;
+          }
+        }
+      } else {
+        this.currentVersion = null;
+        if (this.useMetadata === void 0) {
+          const format = await this.detectDataFormat();
+          this.useMetadata = format.hasMetadata;
+        }
+        if (this.useMetadata) {
+          const destPath = this.getDestinationPath();
+          const metadataPath = path3.join(destPath, "metadata.json");
+          if (fs3.existsSync(metadataPath)) {
+            try {
+              const rawData = await fs3.promises.readFile(metadataPath, "utf8");
+              this.metadata = JSON.parse(rawData);
+              if (this.metadata.files && this.metadata.files.length > 0) {
+                this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+              } else {
+                this.currentFileNumber = 0;
+              }
+            } catch (e) {
+              throw new FileDatabaseError(`Failed to read metadata: ${e.message}`);
+            }
+          } else {
+            throw new FileDatabaseError(
+              `[FileDatabase] No metadata found in non-versioned mode. Looked for: ${metadataPath} (table path: ${destPath})`
+            );
+          }
+        } else {
+          this.metadata = await this.figureMetadataFromVersionFiles("");
+          if (this.metadata.files && this.metadata.files.length > 0) {
+            this.currentFileNumber = Math.max(...this.metadata.files.map((f) => f.number || 0));
+          } else {
+            this.currentFileNumber = 0;
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Write data to the file database
+   */
+  async write(data, options = {}) {
+    if (options.filename) {
+      const destPath2 = this.getDestinationPath();
+      await ensurePath(destPath2);
+      const filePath = path3.join(destPath2, options.filename);
+      await this.safeWrite(filePath, data);
+      return;
+    }
+    if (options.forceNewVersion && !this.versioned) {
+      throw new FileDatabaseError("Cannot use forceNewVersion in non-versioned mode");
+    }
+    await this.prepare({ write: true });
+    const incomingDataType = detectDataType(data);
+    this.metadata.dataType = incomingDataType;
+    if (options.forceNewVersion) {
+      await this.makeNewVersion();
+      this.metadata = this.getDefaultMetadata();
+      this.metadata.version = this.currentVersion;
+      this.metadata.dataType = incomingDataType;
+      this.makeNewFile();
+    }
+    let targetFileIndex = null;
+    const hasCustomMetadata = options.customMetadata && Object.keys(options.customMetadata).length > 0;
+    if (hasCustomMetadata) {
+      for (let i = 0; i < this.metadata.files.length; i++) {
+        const fileEntry = this.metadata.files[i];
+        const matches = Object.keys(options.customMetadata).every((key) => {
+          return key in fileEntry && fileEntry[key] === options.customMetadata[key];
+        });
+        if (matches) {
+          targetFileIndex = i;
+          this.logger.silly?.(`[FileDatabase] Found existing file with matching custom metadata: ${fileEntry.fileName}, metadata: ${JSON.stringify(options.customMetadata)}`);
+          break;
+        } else {
+          this.logger.silly?.(`[FileDatabase] File ${fileEntry.fileName} does not match custom metadata: ${JSON.stringify(options.customMetadata)}`);
+        }
+      }
+      if (targetFileIndex === null) {
+        this.logger.silly?.(`[FileDatabase] No existing file found with custom metadata: ${JSON.stringify(options.customMetadata)}, will create new file`);
+      }
+    } else {
+      this.logger.silly?.(`[FileDatabase] No custom metadata provided, will create new file`);
+    }
+    if (targetFileIndex !== null) {
+      const targetFile = this.metadata.files[targetFileIndex];
+      this.currentFileNumber = targetFile.number;
+      this.lastFileData = null;
+      this.currentRecord = 0;
+      this.hasReadFirstPage = false;
+    }
+    const forceNewFile = hasCustomMetadata && targetFileIndex === null;
+    let { dataToWrite, dataLeftOver, fileName } = this.figureOutDataAndFileToWrite(data, targetFileIndex, forceNewFile);
+    const destPath = this.getDestinationPath(this.currentVersion || void 0);
+    await this.safeWrite(path3.join(destPath, fileName), dataToWrite);
+    this.updateMetadata(dataToWrite, fileName, options.customMetadata);
+    while (dataLeftOver && dataLeftOver.length > 0 && targetFileIndex === null) {
+      const writeContext = this.figureOutDataAndFileToWrite(dataLeftOver);
+      await this.safeWrite(path3.join(destPath, writeContext.fileName), writeContext.dataToWrite);
+      this.updateMetadata(writeContext.dataToWrite, writeContext.fileName, options.customMetadata);
+      dataLeftOver = writeContext.dataLeftOver;
+    }
+    this.calculateVersionSynopsis();
+    if (this.useMetadata) {
+      await this.saveVersionMetadata(this.metadata);
+    }
+  }
+  /**
+   * Read data from the file database
+   */
+  async read(options = {}) {
+    const { version, nextPage = false, pageSize, filename } = options;
+    if (filename) {
+      const destPath = this.getDestinationPath(version);
+      const filePath = path3.join(destPath, filename);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        return JSON.parse(rawData);
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${filename}: ${error.message}`);
+      }
+    }
+    await this.prepare({ read: true, version });
+    const isNonPaginatedData = this.metadata.dataType === "text" || this.metadata.dataType === "xml" || this.metadata.dataType === "json-object";
+    if (isNonPaginatedData) {
+      const file = this.metadata.files[0];
+      const filePath = path3.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        return deserializeData(rawData, this.metadata.dataType);
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${file.fileName}: ${error.message}`);
+      }
+    }
+    let effectivePageSize;
+    if (nextPage && this.hasReadFirstPage) {
+      effectivePageSize = pageSize || this.pageSize;
+      this.currentRecord += effectivePageSize;
+    } else if (!nextPage) {
+      effectivePageSize = pageSize !== void 0 ? pageSize : this.metadata.totalRecords;
+      this.currentRecord = 0;
+    } else {
+      effectivePageSize = pageSize || this.pageSize;
+    }
+    if (this.currentRecord >= this.metadata.totalRecords) {
+      return [];
+    }
+    const result = [];
+    let recordsRead = 0;
+    let currentFileIndex = 0;
+    let currentFileOffset = 0;
+    let totalRecords = 0;
+    for (let i = 0; i < this.metadata.files.length; i++) {
+      const file = this.metadata.files[i];
+      if (this.currentRecord < totalRecords + file.recordsCount) {
+        currentFileIndex = i;
+        currentFileOffset = totalRecords;
+        break;
+      }
+      totalRecords += file.recordsCount;
+    }
+    let cumulativeRecords = currentFileOffset;
+    for (let i = currentFileIndex; i < this.metadata.files.length && recordsRead < effectivePageSize; i++) {
+      const file = this.metadata.files[i];
+      const filePath = path3.join(this.getDestinationPath(this.currentVersion || void 0), file.fileName);
+      try {
+        const rawData = await fs3.promises.readFile(filePath, "utf8");
+        const fileData = deserializeData(rawData, this.metadata.dataType);
+        let startIndex = 0;
+        if (i === currentFileIndex) {
+          startIndex = this.currentRecord - cumulativeRecords;
+        }
+        const endIndex = Math.min(startIndex + (effectivePageSize - recordsRead), fileData.length);
+        const recordsFromThisFile = fileData.slice(startIndex, endIndex);
+        result.push(...recordsFromThisFile);
+        recordsRead += recordsFromThisFile.length;
+        cumulativeRecords += file.recordsCount;
+      } catch (error) {
+        throw new FileDatabaseError(`Failed to read file ${file.fileName}: ${error.message}`);
+      }
+    }
+    if (result.length > 0) {
+      if (nextPage || pageSize !== void 0 && pageSize < this.metadata.totalRecords) {
+        this.hasReadFirstPage = true;
+      }
+    }
+    return result;
+  }
+  /**
+   * Set the starting record for pagination (1-based index)
+   */
+  setStartRecord(startRecord) {
+    this.currentRecord = startRecord - 1;
+    this.hasReadFirstPage = false;
+  }
+  /**
+   * Reset read pagination state
+   */
+  resetPagination() {
+    this.currentRecord = 0;
+    this.hasReadFirstPage = false;
+  }
+  /**
+   * List filenames in the table directory.
+   * For catalog/key-value usage (files written with { filename }).
+   * Returns data file names (.json, .txt, .xml) excluding metadata.json.
+   */
+  async listFilenames() {
+    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    try {
+      const entries = await fs3.promises.readdir(destPath, { withFileTypes: true });
+      return entries.filter((e) => e.isFile() && e.name !== "metadata.json" && /\.(json|txt|xml)$/i.test(e.name)).map((e) => e.name);
+    } catch (err) {
+      if (err?.code === "ENOENT") return [];
+      throw new FileDatabaseError(`Failed to list files: ${err.message}`);
+    }
+  }
+  /**
+   * Remove a file from the table directory (catalog mode).
+   * Use with listFilenames() to manage individual files.
+   */
+  async removeFile(filename) {
+    const destPath = this.versioned && this.currentVersion ? path3.join(this.getDestinationPath(), this.currentVersion) : this.getDestinationPath();
+    const filePath = path3.join(destPath, filename);
+    try {
+      await fs3.promises.unlink(filePath);
+    } catch (err) {
+      if (err?.code === "ENOENT") return;
+      throw new FileDatabaseError(`Failed to remove file ${filename}: ${err.message}`);
+    }
+  }
+  /**
+   * Remove a file and its metadata entry (non-versioned mode with useMetadata).
+   * Use with findData() to get fileName, then call removeFileEntry to delete.
+   */
+  async removeFileEntry(filename) {
+    if (this.versioned) {
+      throw new FileDatabaseError("removeFileEntry is only supported in non-versioned mode");
+    }
+    await this.prepare({ read: true });
+    const idx = this.metadata.files.findIndex((f) => f.fileName === filename);
+    if (idx === -1) {
+      throw new FileDatabaseError(`File entry ${filename} not found in metadata`);
+    }
+    const entry = this.metadata.files[idx];
+    const recordsCount = entry.recordsCount || 0;
+    this.metadata.files.splice(idx, 1);
+    this.metadata.totalRecords = Math.max(0, (this.metadata.totalRecords || 0) - recordsCount);
+    const destPath = this.getDestinationPath();
+    const filePath = path3.join(destPath, filename);
+    try {
+      await fs3.promises.unlink(filePath);
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        this.logger.warn?.(`[FileDatabase] File ${filename} already missing on disk`);
+      } else {
+        throw new FileDatabaseError(`Failed to remove file ${filename}: ${err.message}`);
+      }
+    }
+    if (this.useMetadata) {
+      await this.saveVersionMetadata(this.metadata);
+    }
+  }
+  /**
+   * Set file-level synopsis calculation function
+   */
+  setFileSynopsisFunction(fn) {
+    this.fileSynopsisFunction = fn;
+  }
+  /**
+   * Set version-level synopsis calculation function
+   */
+  setVersionSynopsisFunction(fn) {
+    this.versionSynopsisFunction = fn;
+  }
+  /**
+   * Get current version name
+   */
+  getCurrentVersion() {
+    return this.currentVersion;
+  }
+  /**
+   * Get current metadata
+   */
+  getMetadata() {
+    return { ...this.metadata };
+  }
+  /**
+   * Find data by custom metadata fields
+   * Searches through all versions and files to find entries matching the search criteria
+   * 
+   * @param searchCriteria - Object with field names and values to search for (e.g., { ListingKey: "123", id: "456" })
+   * @returns Array of found entries with their file paths and metadata
+   */
+  async findData(searchCriteria) {
+    const results = [];
+    if (!this.versioned) {
+      await this.prepare({ read: true });
+      const metadata = this.getMetadata();
+      for (const fileEntry of metadata.files) {
+        const matches = Object.keys(searchCriteria).every((key) => {
+          return fileEntry[key] === searchCriteria[key];
+        });
+        if (matches) {
+          const destPath = this.getDestinationPath();
+          const filePath = path3.join(destPath, fileEntry.fileName);
+          const fileData = await fs3.promises.readFile(filePath, "utf8");
+          const data = deserializeData(fileData, metadata.dataType || "json-object");
+          results.push({
+            filePath,
+            fileName: fileEntry.fileName,
+            version: null,
+            metadata: fileEntry,
+            data
+          });
+        }
+      }
+    } else {
+      const versions = await this.getVersions();
+      for (const version of versions) {
+        await this.prepare({ read: true, version });
+        const metadata = this.getMetadata();
+        for (const fileEntry of metadata.files) {
+          const matches = Object.keys(searchCriteria).every((key) => {
+            return fileEntry[key] === searchCriteria[key];
+          });
+          if (matches) {
+            const destPath = this.getDestinationPath(version);
+            const filePath = path3.join(destPath, fileEntry.fileName);
+            const fileData = await fs3.promises.readFile(filePath, "utf8");
+            const data = deserializeData(fileData, metadata.dataType || "json-object");
+            results.push({
+              filePath,
+              fileName: fileEntry.fileName,
+              version,
+              metadata: fileEntry,
+              data
+            });
+          }
+        }
+      }
+    }
+    return results;
+  }
+};
+
+// src/tasks/taskLogs.ts
+function getLogsState(context) {
+  const holder = context;
+  if (holder.__tasksLogsState) return holder.__tasksLogsState;
+  const basePath = holder.params?.get?.("tasksLogsBasePath") || "./data";
+  const namespace = holder.params?.get?.("tasksLogsNamespace") || "tasks-logs";
+  const tableName = holder.params?.get?.("tasksLogsTable") || "runner";
+  const errorTableName = holder.params?.get?.("tasksErrorLogsTable") || `${tableName}-errors`;
+  const maxVersionsRaw = Number(holder.params?.get?.("tasksLogsMaxVersions"));
+  const pageSizeRaw = Number(holder.params?.get?.("tasksLogsPageSize"));
+  const errorDb = new FileDatabase({
+    basePath,
+    namespace,
+    tableName: errorTableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const enabledRaw = holder.params?.get?.("tasksLogsEnabled");
+  const enabled = enabledRaw === void 0 ? true : !!enabledRaw;
+  if (!enabled) {
+    const disabledState = {
+      db: null,
+      errorDb,
+      queue: Promise.resolve(),
+      initialized: true,
+      errorInitialized: false
+    };
+    holder.__tasksLogsState = disabledState;
+    return disabledState;
+  }
+  const db = new FileDatabase({
+    basePath,
+    namespace,
+    tableName,
+    versioned: true,
+    useMetadata: true,
+    maxVersions: Number.isFinite(maxVersionsRaw) && maxVersionsRaw > 0 ? maxVersionsRaw : 20,
+    pageSize: Number.isFinite(pageSizeRaw) && pageSizeRaw > 0 ? pageSizeRaw : 2e3,
+    logger: holder.logger
+  });
+  const state = {
+    db,
+    errorDb,
+    queue: Promise.resolve(),
+    initialized: false,
+    errorInitialized: false
+  };
+  holder.__tasksLogsState = state;
+  return state;
+}
+function isErrorPayload(payload) {
+  if (!payload) return false;
+  if (typeof payload === "object") {
+    const level = typeof payload.level === "string" ? payload.level.toLowerCase() : "";
+    if (level === "error" || level === "fatal") return true;
+    if (typeof payload.message === "string" && /\berror\b/i.test(payload.message)) return true;
+    return false;
+  }
+  if (typeof payload === "string") {
+    return /\berror\b/i.test(payload);
+  }
+  return false;
+}
+function buildLogRecord(task, payload) {
+  const params = task.params && typeof task.params === "object" ? task.params : {};
+  return {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    opid: task.opid ?? null,
+    taskId: task.id,
+    taskName: task.task,
+    target: task.target,
+    source: typeof params.source === "string" ? params.source : null,
+    resource: typeof params.resource === "string" ? params.resource : null,
+    payload
+  };
+}
+function appendTaskIpcLog(context, task, payload) {
+  const state = getLogsState(context);
+  if (!state.db && !state.errorDb) return;
+  const record = buildLogRecord(task, payload);
+  state.queue = state.queue.then(async () => {
+    if (state.db) {
+      await state.db.write([record], { forceNewVersion: !state.initialized });
+      state.initialized = true;
+    }
+    if (state.errorDb && isErrorPayload(payload)) {
+      await state.errorDb.write([record], { forceNewVersion: !state.errorInitialized });
+      state.errorInitialized = true;
+    }
+  }).catch((error) => {
+    context.logger.warn?.("[tasks] failed to persist IPC log entry:", error);
+  });
+}
+
+// src/tasks/time-matcher.ts
+var RANGES = ["0-59", "0-59", "0-23", "1-31", "1-12", "0-6"];
+function resolveAsterisks(field, range) {
+  return field.includes("*") ? field.replace("*", range) : field;
+}
+function resolveRanges(field) {
+  const regex = /(\d+)-(\d+)/;
+  let current = field;
+  while (true) {
+    const match = regex.exec(current);
+    if (!match) break;
+    const raw = match[0];
+    let first = Number(match[1]);
+    let last = Number(match[2]);
+    if (last < first) {
+      [first, last] = [last, first];
+    }
+    const values = [];
+    for (let i = first; i <= last; i += 1) {
+      values.push(i);
+    }
+    current = current.replace(raw, values.join(","));
+  }
+  return current;
+}
+function resolveSteps(field) {
+  const match = /^(.+)\/(\d+)$/.exec(field);
+  if (!match) return field;
+  const base = match[1];
+  const step = Number(match[2]);
+  if (!Number.isFinite(step) || step <= 0) return field;
+  return base.split(",").map((v) => Number(v)).filter((v) => Number.isFinite(v) && v % step === 0).join(",");
+}
+function convertPattern(pattern) {
+  const parts = pattern.trim().split(/\s+/);
+  if (parts.length !== 6) {
+    throw new Error(`Invalid schedule "${pattern}". Expected 6 fields: sec min hour day month weekday`);
+  }
+  return parts.map((field, idx) => resolveAsterisks(field, RANGES[idx])).map((field) => resolveRanges(field)).map((field) => resolveSteps(field));
+}
+function fieldMatches(field, value) {
+  const allowed = field.split(",").map((v) => Number(v));
+  return allowed.includes(value);
+}
+function timeMatcher(pattern, date = /* @__PURE__ */ new Date()) {
+  const parsed = convertPattern(pattern);
+  return fieldMatches(parsed[0], date.getSeconds()) && fieldMatches(parsed[1], date.getMinutes()) && fieldMatches(parsed[2], date.getHours()) && fieldMatches(parsed[3], date.getDate()) && fieldMatches(parsed[4], date.getMonth() + 1) && fieldMatches(parsed[5], date.getDay());
+}
+
+// src/tasks/TaskMaster.ts
+var TaskMaster = class {
+  context;
+  task;
+  constructor(context, task) {
+    this.context = context;
+    this.task = task;
+  }
+  cantRunReason() {
+    return false;
+  }
+  requestStop(_allowanceMs) {
+  }
+};
+
+// src/tasks/coreTasks/TaskPing.ts
+var TaskPing = class extends TaskMaster {
+  async run() {
+    this.context.logger.info?.(`[TaskPing] pong (${this.task.id})`);
+    return { success: true, results: "pong" };
+  }
+};
+
+// src/tasks/coreTasks/TaskSampleProcess.ts
+var TaskSampleProcess = class extends TaskMaster {
+  stopRequested = false;
+  stopAllowanceMs = 0;
+  stopDecisionLogged = false;
+  requestStop(allowanceMs) {
+    this.stopRequested = true;
+    this.stopAllowanceMs = Number.isFinite(allowanceMs) && allowanceMs > 0 ? allowanceMs : 0;
+    this.context.logger.warn?.(
+      `[TaskSampleProcess] stop signal received (${this.task.id}), allowanceMs=${this.stopAllowanceMs}`
+    );
+  }
+  async run(reportProgress) {
+    const totalRaw = this.task?.params?.total ?? 10;
+    const delayRaw = this.task?.params?.delay ?? 1e3;
+    const nameRaw = this.task?.params?.name;
+    const total = Number(totalRaw);
+    const delay = Number(delayRaw);
+    const name = typeof nameRaw === "string" && nameRaw.trim() ? nameRaw.trim() : "sampleProcess";
+    const errors = [];
+    if (!Number.isInteger(total) || total <= 0) {
+      errors.push('param "total" must be a positive integer');
+    }
+    if (!Number.isInteger(delay) || delay < 0) {
+      errors.push('param "delay" must be an integer >= 0');
+    }
+    if (errors.length > 0) {
+      return {
+        success: false,
+        results: {
+          error: `Validation failed: ${errors.join(", ")}`,
+          received: { total: totalRaw, delay: delayRaw, name: nameRaw }
+        }
+      };
+    }
+    const startedAt = Date.now();
+    for (let i = 1; i <= total; i += 1) {
+      if (this.stopRequested) {
+        const remainingMs = Math.max(0, (total - i + 1) * delay);
+        if (remainingMs <= this.stopAllowanceMs) {
+          if (!this.stopDecisionLogged) {
+            this.stopDecisionLogged = true;
+            this.context.logger.warn?.(
+              `[TaskSampleProcess] continue to finish (${this.task.id}): remainingMs=${remainingMs} <= allowanceMs=${this.stopAllowanceMs}`
+            );
+          }
+        } else {
+          this.context.logger.warn?.(
+            `[TaskSampleProcess] stopping gracefully at iteration ${i}/${total} (${this.task.id}), remainingMs=${remainingMs} > allowanceMs=${this.stopAllowanceMs}`
+          );
+          return {
+            success: false,
+            results: {
+              message: `Stopped before completion at iteration ${i}/${total}`,
+              completed: i - 1,
+              total,
+              name,
+              remainingMs,
+              allowanceMs: this.stopAllowanceMs
+            }
+          };
+        }
+      }
+      const elapsed = Date.now() - startedAt;
+      const remaining = Math.max(0, (total - i) * delay);
+      const progress = {
+        name,
+        count: i,
+        total,
+        elapsedMs: elapsed,
+        remainingMs: remaining,
+        status: `running ${name}: ${i}/${total}`
+      };
+      this.context.logger.progress("running", {
+        prefix: name,
+        count: i,
+        total
+      });
+      await reportProgress(progress);
+      await sleepMs(delay);
+    }
+    return {
+      success: true,
+      results: {
+        message: `Completed ${total} iterations`,
+        total,
+        delay,
+        name
+      }
+    };
+  }
+};
+
+// src/tasks/coreTasks/TaskShellCommand.ts
+import { spawn } from "child_process";
+function runShellCommand(command, cwd) {
+  return new Promise((resolve2, reject) => {
+    const child = spawn(command, {
+      shell: true,
+      cwd: cwd || process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let output = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      output += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      reject(error);
+    });
+    child.on("close", (exitCode, signal) => {
+      resolve2({
+        exitCode,
+        output: output.trim(),
+        stderr: stderr.trim(),
+        signal
+      });
+    });
+  });
+}
+var TaskShellCommand = class extends TaskMaster {
+  async run() {
+    const params = this.task?.params;
+    const commandRaw = typeof params === "string" ? params : params?.command;
+    const cwdRaw = typeof params === "string" ? void 0 : params?.cwd;
+    const command = typeof commandRaw === "string" ? commandRaw.trim() : "";
+    const cwd = typeof cwdRaw === "string" && cwdRaw.trim() ? cwdRaw.trim() : void 0;
+    if (!command) {
+      return {
+        success: false,
+        results: {
+          error: 'Validation failed: param "command" must be a non-empty string',
+          received: this.task?.params ?? null
+        }
+      };
+    }
+    try {
+      const result = await runShellCommand(command, cwd);
+      const success = result.exitCode === 0;
+      this.context.logger.info?.(
+        `[TaskShellCommand] command="${command}" exitCode=${String(result.exitCode)} (${this.task.id})`
+      );
+      return {
+        success,
+        results: {
+          command,
+          cwd: cwd ?? process.cwd(),
+          output: result.output,
+          stderr: result.stderr,
+          exitCode: result.exitCode,
+          signal: result.signal
+        }
+      };
+    } catch (error) {
+      return {
+        success: false,
+        results: {
+          command,
+          cwd: cwd ?? process.cwd(),
+          output: "",
+          stderr: "",
+          exitCode: null,
+          error: error?.message ?? String(error)
+        }
+      };
+    }
+  }
+};
+
+// src/tasks/coreTasks/TaskSystemInfo.ts
+import os from "os";
+import fs4 from "fs/promises";
+function toGb(valueBytes) {
+  return `${(valueBytes / 1024 ** 3).toFixed(2)} GB`;
+}
+function toMb(valueBytes) {
+  return `${(valueBytes / 1024 ** 2).toFixed(2)} MB`;
+}
+async function getDiskStats() {
+  const stats = await fs4.statfs("/");
+  const total = Number(stats.bsize) * Number(stats.blocks);
+  const free = Number(stats.bsize) * Number(stats.bavail);
+  const used = total - free;
+  return {
+    total: toGb(total),
+    used: toGb(used),
+    free: toGb(free)
+  };
+}
+var TaskSystemInfo = class extends TaskMaster {
+  async run() {
+    try {
+      const totalMemory = os.totalmem();
+      const freeMemory = os.freemem();
+      const usedMemory = totalMemory - freeMemory;
+      const cpus = os.cpus();
+      const cpuUtilization = cpus.map((cpu) => {
+        const total = Object.values(cpu.times).reduce((acc, time) => acc + time, 0);
+        const usage = (total - cpu.times.idle) / total * 100;
+        return Number(usage.toFixed(2));
+      });
+      const processMemory = process.memoryUsage();
+      const disk = await getDiskStats();
+      const results = {
+        memory: {
+          total: toGb(totalMemory),
+          used: toGb(usedMemory),
+          free: toGb(freeMemory)
+        },
+        processMemory: {
+          rss: toMb(processMemory.rss),
+          heapTotal: toMb(processMemory.heapTotal),
+          heapUsed: toMb(processMemory.heapUsed),
+          external: toMb(processMemory.external)
+        },
+        disk,
+        cpu: {
+          cores: cpuUtilization.length,
+          utilization: cpuUtilization
+        },
+        runtime: {
+          platform: os.platform(),
+          arch: os.arch(),
+          uptimeSec: os.uptime(),
+          hostname: os.hostname()
+        }
+      };
+      this.context.logger.info?.(`[TaskSystemInfo] collected system metrics (${this.task.id})`);
+      return { success: true, results };
+    } catch (error) {
+      return {
+        success: false,
+        results: {
+          error: "Can't collect system stats",
+          message: error?.message ?? String(error)
+        }
+      };
+    }
+  }
+};
+
+// src/tasks/coreTasks/TaskSumAB.ts
+var TaskSumAB = class extends TaskMaster {
+  async run() {
+    const a = this.task?.params?.a;
+    const b = this.task?.params?.b;
+    if (typeof a !== "number" || Number.isNaN(a)) {
+      return {
+        success: false,
+        results: {
+          error: 'Validation failed: param "a" must be a valid number',
+          received: { a, b }
+        }
+      };
+    }
+    if (typeof b !== "number" || Number.isNaN(b)) {
+      return {
+        success: false,
+        results: {
+          error: 'Validation failed: param "b" must be a valid number',
+          received: { a, b }
+        }
+      };
+    }
+    const sum = a + b;
+    this.context.logger.info?.(`[TaskSumAB] ${a} + ${b} = ${sum} (${this.task.id})`);
+    return {
+      success: true,
+      results: { a, b, sum }
+    };
+  }
+};
+
+// src/tasks/coreTasks/TaskStopRunner.ts
+var TaskStopRunner = class extends TaskMaster {
+  async run() {
+    const allowanceMs = Number(this.task?.params?.allowanceMs ?? 5e3);
+    this.context.logger.warn?.(`[TaskStopRunner] stop requested (allowanceMs=${allowanceMs})`);
+    return {
+      success: true,
+      results: {
+        stopRunner: true,
+        allowanceMs,
+        message: "Runner stop requested"
+      }
+    };
+  }
+};
+
+// src/tasks/TasksRegistry.ts
+var TasksRegistry = class _TasksRegistry {
+  map = {};
+  constructor(initial) {
+    if (initial) {
+      this.addMany(initial);
+    }
+  }
+  static withCoreTasks() {
+    return new _TasksRegistry().add("ping", TaskPing).add("sampleProcess", TaskSampleProcess).add("shellCommand", TaskShellCommand).add("systemInfo", TaskSystemInfo).add("taskSumAB", TaskSumAB).add("stopRunner", TaskStopRunner).add("stop", TaskStopRunner);
+  }
+  add(taskName, taskClass) {
+    this.map[taskName] = taskClass;
+    return this;
+  }
+  addMany(entries) {
+    for (const [name, klass] of Object.entries(entries)) {
+      this.add(name, klass);
+    }
+    return this;
+  }
+  get(taskName) {
+    return this.map[taskName];
+  }
+  listSupportedTasks() {
+    return Object.keys(this.map).sort();
+  }
+  toObject() {
+    return { ...this.map };
+  }
+};
+
+// src/tasks/taskScriptRunner.ts
+import { spawn as spawn2 } from "child_process";
+
+// src/tasks/index.ts
+var LOCKED_BY_ERROR_MESSAGE = "locked by error";
+var defaultTasksRegistry = TasksRegistry.withCoreTasks();
+function getDb2(context) {
+  const db = context.db;
+  if (!db) {
+    throw new Error("Tasks component requires context.db. Initialize DB first and attach to context.");
+  }
+  return db;
+}
+function normalizeRegistry(registry) {
+  if (!registry) return defaultTasksRegistry;
+  if (registry instanceof TasksRegistry) return registry;
+  return new TasksRegistry().addMany(registry);
+}
+function normalizeAllowedTasks(value) {
+  if (!value) return void 0;
+  if (Array.isArray(value)) {
+    const out2 = value.map((v) => String(v).trim()).filter(Boolean);
+    return out2.length ? out2 : void 0;
+  }
+  const out = String(value).split(",").map((v) => v.trim()).filter(Boolean);
+  return out.length ? out : void 0;
+}
+async function signalRunningTasksStop(context, runningTaskInstances, allowanceMs) {
+  context.logger.warn?.(`[tasks] signaling ${runningTaskInstances.size} running task(s) to stop`);
+  for (const [, taskInstance] of runningTaskInstances) {
+    if (typeof taskInstance.requestStop === "function") {
+      try {
+        await taskInstance.requestStop(allowanceMs);
+      } catch (error) {
+        context.logger.warn?.("[tasks] task requestStop failed:", error);
+      }
+    }
+  }
+  context.emitter.emit("stop", allowanceMs);
+}
+async function executeClaimedTask(context, tasksTable, historyTable, row, registry, runningTaskInstances) {
+  const db = getDb2(context);
+  const taskName = row.task;
+  const TaskClass = registry.get(taskName);
+  const { paused_at: _pausedAt, ...rowForHistory } = row;
+  if (!TaskClass) {
+    const err = { message: `Unknown task "${taskName}"` };
+    await db(historyTable).insert({
+      ...rowForHistory,
+      completed_at: /* @__PURE__ */ new Date(),
+      success: false,
+      params: toJsonColumn(row.params),
+      results: toJsonColumn(err)
+    });
+    if (row.schedule) {
+      await db(tasksTable).where({ id: row.id }).update({
+        started_at: null,
+        completed_at: /* @__PURE__ */ new Date(),
+        success: false,
+        results: toJsonColumn(err),
+        past_due: null,
+        paused_at: db.fn.now(),
+        progress: LOCKED_BY_ERROR_MESSAGE
+      });
+    } else {
+      await db(tasksTable).where({ id: row.id }).delete();
+    }
+    return { stopRunnerRequested: false, stopAllowanceMs: 0 };
+  }
+  let success = false;
+  let results = null;
+  let taskInstance = null;
+  try {
+    taskInstance = new TaskClass(context, row);
+    runningTaskInstances.set(row.id, taskInstance);
+    const runResult = await taskInstance.run((progress) => updateTaskProgress(context, tasksTable, row.id, progress));
+    success = !!runResult?.success;
+    results = runResult?.results ?? null;
+  } catch (error) {
+    success = false;
+    results = {
+      message: error?.message ?? String(error),
+      name: error?.name ?? "Error",
+      stack: error?.stack ?? null
+    };
+  } finally {
+    runningTaskInstances.delete(row.id);
+  }
+  await db(historyTable).insert({
+    ...rowForHistory,
+    completed_at: /* @__PURE__ */ new Date(),
+    success,
+    params: toJsonColumn(row.params),
+    results: toJsonColumn(results)
+  });
+  if (!success) {
+    const dbName = String(context?.params?.get?.("dbName") || "local");
+    const tableName = String(context?.params?.get?.("table") || "tasks");
+    const fallbackRecoverCommand = [
+      "npx",
+      "tsx",
+      "examples/tasks/recover-task.ts",
+      `--dbName='${dbName.replace(/'/g, `'\\''`)}'`,
+      `--table='${tableName.replace(/'/g, `'\\''`)}'`,
+      `--id='${String(row.id).replace(/'/g, `'\\''`)}'`
+    ].join(" ");
+    const rerunCommand = results && typeof results === "object" && results.rerunCommand ? results.rerunCommand : fallbackRecoverCommand;
+    appendTaskIpcLog(context, row, {
+      level: "error",
+      message: `[tasks] task failed: ${row.task} id=${row.id}. Once problem is fixed, re-run: ${rerunCommand}`,
+      details: results
+    });
+  }
+  if (row.schedule) {
+    if (success) {
+      await db(tasksTable).where({ id: row.id }).update({
+        started_at: null,
+        completed_at: /* @__PURE__ */ new Date(),
+        success,
+        results: toJsonColumn(results),
+        progress: null,
+        past_due: null
+      });
+    } else {
+      await db(tasksTable).where({ id: row.id }).update({
+        started_at: null,
+        completed_at: /* @__PURE__ */ new Date(),
+        success,
+        results: toJsonColumn(results),
+        paused_at: db.fn.now(),
+        progress: LOCKED_BY_ERROR_MESSAGE,
+        past_due: null
+      });
+    }
+  } else {
+    await db(tasksTable).where({ id: row.id }).delete();
+  }
+  const stopRunnerRequested = !!(results && typeof results === "object" && results.stopRunner === true);
+  const stopAllowanceMs = stopRunnerRequested ? Number(results.allowanceMs ?? 5e3) : 0;
+  return { stopRunnerRequested, stopAllowanceMs };
+}
+async function claimNextRunnableTask(context, tasksTable, target, registry, scanLimit, taskNames) {
+  const db = getDb2(context);
+  let query = db(tasksTable).whereNull("started_at").whereNull("paused_at").where({ target }).orderByRaw("CASE WHEN past_due IS NULL THEN 1 ELSE 0 END ASC").orderBy([{ column: "priority", order: "desc" }]).orderByRaw("CASE WHEN completed_at IS NULL THEN 0 ELSE 1 END ASC").orderBy([{ column: "completed_at", order: "asc" }, { column: "created_at", order: "asc" }]).limit(scanLimit);
+  if (taskNames && taskNames.length > 0) {
+    query = query.whereIn("task", taskNames);
+  }
+  const candidates = await query;
+  for (const row of candidates) {
+    if (!row.past_due && row.schedule && !timeMatcher(row.schedule)) {
+      continue;
+    }
+    const TaskClass = registry.get(row.task);
+    if (TaskClass) {
+      const taskInstance = new TaskClass(context, row);
+      const reason = taskInstance.cantRunReason ? await taskInstance.cantRunReason() : null;
+      if (reason) {
+        if (!row.past_due) {
+          await db(tasksTable).where({ id: row.id }).update({
+            past_due: db.fn.now(),
+            progress: String(reason)
+          });
+        }
+        continue;
+      }
+    }
+    const updated = await db(tasksTable).where({ id: row.id }).whereNull("started_at").whereNull("paused_at").update({ started_at: db.fn.now() }).returning("*");
+    const claimed = Array.isArray(updated) ? updated[0] : null;
+    if (claimed) return claimed;
+  }
+  return null;
+}
+async function runTasksLoop(context, options) {
+  const queue = options.queue ?? "tasks";
+  const target = options.target;
+  const pollMs = options.pollMs ?? 1e3;
+  const maxParallel = options.maxParallel ?? 1;
+  const scanLimit = options.scanLimit ?? 100;
+  const allowedTasks = normalizeAllowedTasks(options.allowedTasks);
+  const registry = normalizeRegistry(options.registry);
+  const { tasksTable, historyTable } = queueToTableNames(queue);
+  if (!target) throw new Error("runTasksLoop: target is required");
+  const runningPromises = /* @__PURE__ */ new Set();
+  const runningTaskInstances = /* @__PURE__ */ new Map();
+  let runningStopControlPromise = null;
+  let stopRequested = false;
+  let stopAllowanceMs = 5e3;
+  context.__tasksRunnerStop = false;
+  while (!context.isStop() && !stopRequested && !context.__tasksRunnerStop) {
+    if (!runningStopControlPromise) {
+      const claimedStopTask = await claimNextRunnableTask(
+        context,
+        tasksTable,
+        target,
+        registry,
+        10,
+        ["stopRunner", "stop"]
+      );
+      if (claimedStopTask) {
+        runningStopControlPromise = executeClaimedTask(
+          context,
+          tasksTable,
+          historyTable,
+          claimedStopTask,
+          registry,
+          runningTaskInstances
+        ).then(async (outcome) => {
+          if (outcome.stopRunnerRequested && !stopRequested) {
+            stopRequested = true;
+            stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
+            context.__tasksRunnerStop = true;
+            await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
+          }
+        }).finally(() => {
+          runningStopControlPromise = null;
+        });
+      }
+    }
+    while (runningPromises.size < maxParallel) {
+      const claimed = await claimNextRunnableTask(
+        context,
+        tasksTable,
+        target,
+        registry,
+        scanLimit,
+        allowedTasks
+      );
+      if (!claimed) break;
+      const p = executeClaimedTask(context, tasksTable, historyTable, claimed, registry, runningTaskInstances).then(async (outcome) => {
+        if (outcome.stopRunnerRequested && !stopRequested) {
+          stopRequested = true;
+          stopAllowanceMs = outcome.stopAllowanceMs || 5e3;
+          context.__tasksRunnerStop = true;
+          await signalRunningTasksStop(context, runningTaskInstances, stopAllowanceMs);
+        }
+      }).finally(() => {
+        runningPromises.delete(p);
+      });
+      runningPromises.add(p);
+    }
+    await sleepMs(pollMs);
+  }
+  if (context.isStop() && !stopRequested) {
+    await signalRunningTasksStop(context, runningTaskInstances, 5e3);
+  }
+  if (runningPromises.size > 0) {
+    if (stopRequested) {
+      await Promise.race([
+        Promise.allSettled(Array.from(runningPromises)),
+        sleepMs(stopAllowanceMs).then(() => {
+          context.logger.warn?.(
+            `[tasks] stop allowance (${stopAllowanceMs}ms) reached; ${runningPromises.size} task(s) still running`
+          );
+        })
+      ]);
+    } else {
+      await Promise.allSettled(Array.from(runningPromises));
+    }
+  }
+}
+var TasksManager = class _TasksManager {
+  context;
+  queue;
+  target;
+  recreateTaskTables;
+  pollMs;
+  maxParallel;
+  scanLimit;
+  allowedTasks;
+  registry;
+  constructor(context, options = {}) {
+    this.context = context;
+    this.queue = options.queue ?? "tasks";
+    this.target = options.target ?? "localRunner";
+    this.recreateTaskTables = options.recreateTaskTables ?? false;
+    this.pollMs = options.pollMs ?? 1e3;
+    this.maxParallel = options.maxParallel ?? 1;
+    this.scanLimit = options.scanLimit ?? 100;
+    this.allowedTasks = normalizeAllowedTasks(options.allowedTasks);
+    this.registry = normalizeRegistry(options.registry);
+  }
+  static init(context, options = {}) {
+    const defs2 = {
+      table: "string default tasks",
+      target: "string default localRunner",
+      recreateTaskTables: "boolean default false",
+      pollMs: "number default 1000",
+      maxParallel: "number default 1",
+      scanLimit: "number default 100",
+      allowedTasks: "string"
+    };
+    const discovered = context.params.getAllForModule(defs2);
+    const resolved = {
+      queue: discovered.table,
+      target: discovered.target,
+      recreateTaskTables: discovered.recreateTaskTables,
+      pollMs: discovered.pollMs,
+      maxParallel: discovered.maxParallel,
+      scanLimit: discovered.scanLimit,
+      allowedTasks: discovered.allowedTasks,
+      ...options
+    };
+    return new _TasksManager(context, resolved);
+  }
+  async ensureTaskTables(options = {}) {
+    await ensureTaskTables(this.context, {
+      queue: this.queue,
+      recreate: options.recreate ?? this.recreateTaskTables
+    });
+  }
+  async runTasksLoop(options = {}) {
+    await runTasksLoop(this.context, {
+      queue: options.queue ?? this.queue,
+      target: options.target ?? this.target,
+      pollMs: options.pollMs ?? this.pollMs,
+      maxParallel: options.maxParallel ?? this.maxParallel,
+      scanLimit: options.scanLimit ?? this.scanLimit,
+      allowedTasks: options.allowedTasks ?? this.allowedTasks,
+      registry: options.registry ?? this.registry
+    });
+  }
+};
+
+// src/scripts/cli-runner.ts
+var defs = {
+  dbName: "string default local",
+  tasksModule: "string"
+};
+async function loadTasksModule(modulePath) {
+  const absolute = path4.isAbsolute(modulePath) ? modulePath : path4.resolve(process.cwd(), modulePath);
+  const imported = await import(pathToFileURL(absolute).href);
+  if (!imported.tasksRegistry || typeof imported.tasksRegistry !== "object") {
+    throw new Error(`tasksModule "${modulePath}" must export "tasksRegistry" object`);
+  }
+  return imported.tasksRegistry;
+}
+var flow = async (context) => {
+  const {
+    dbName,
+    tasksModule
+  } = context.params.getAll(defs);
+  const db = await dbInit(context, dbName);
+  context.db = db;
+  const registry = new TasksRegistry().addMany(defaultTasksRegistry.toObject());
+  if (tasksModule) {
+    const externalRegistry = await loadTasksModule(tasksModule);
+    registry.addMany(externalRegistry);
+  }
+  const tasksManager = TasksManager.init(context, {
+    registry
+  });
+  await tasksManager.ensureTaskTables();
+  await tasksManager.runTasksLoop();
+};
+void init(flow);
+//# sourceMappingURL=cli-runner.js.map