@apisurf/ngn-core 0.2.2

package/dist/core.js

@@ -0,0 +1,1217 @@
+// src/source/compiler.ts
+import invariant from "tiny-invariant";
+import * as esbuild from "esbuild";
+var Compiler = class {
+  options;
+  externalizePlugin;
+  constructor(options = {}) {
+    this.options = {
+      minify: options.minify ?? false,
+      sourcemap: options.sourcemap ?? false,
+      silent: options.silent ?? true,
+      // bundle all ngn packages by default
+      noExternal: options.noExternal ?? [/^ngn-(.*)/, /^@apisurf\/(.*)/]
+    };
+    this.externalizePlugin = this.createExternalizePlugin();
+  }
+  /**
+   * Creates an esbuild plugin that externalizes all bare package imports
+   * except for those matching the noExternal patterns.
+   * This approach automatically handles all dependencies (including transitive ones)
+   * without needing to maintain a list or read package.json.
+   *
+   * NOTE: There are esbuild config options that can be used to externalize dependencies
+   * but they are not as flexible as this plugin. This plugin is more flexible and
+   * can be used to externalize dependencies that are not in the package.json(alternative approach).
+   * Previous implementations used tsup which did this by default or used a list of
+   * dependencies to externalize. This approach externalizes everything dynamically.
+   * Problematic dependencies were: playwright, playwright-core, chromium-bidi, etc.
+   */
+  createExternalizePlugin() {
+    const noExternalPatterns = this.options.noExternal || [];
+    return {
+      name: "externalize-deps",
+      setup(build2) {
+        build2.onResolve({ filter: /^[^./]/ }, (args) => {
+          const parts = args.path.split("/");
+          const pkgName = args.path.startsWith("@") ? `${parts[0]}/${parts[1]}` : parts[0];
+          const shouldBundle = noExternalPatterns.some((pattern) => {
+            if (typeof pattern === "string") {
+              return pkgName === pattern || args.path === pattern;
+            }
+            return pattern.test(pkgName) || pattern.test(args.path);
+          });
+          if (shouldBundle) {
+            return null;
+          }
+          return { path: args.path, external: true };
+        });
+      }
+    };
+  }
+  /**
+   * Compile entry files to in-memory strings (no disk I/O)
+   * @param entry - Array of input paths
+   * @returns Map of input file path to compiled code string
+   */
+  async compile(entry) {
+    invariant(entry, "Entry file(s) not provided");
+    const compiled = /* @__PURE__ */ new Map();
+    for (const entryFile of entry) {
+      const result = await esbuild.build({
+        entryPoints: [entryFile],
+        bundle: true,
+        write: false,
+        // Output as IIFE (Immediately Invoked Function Expression) so it can be
+        // executed with vm.Script in a sandboxed context. The globalName specifies
+        // which variable the exports are assigned to: var __exports = (() => { ... })();
+        format: "iife",
+        globalName: "__exports",
+        platform: "node",
+        target: "node20",
+        minify: this.options.minify,
+        sourcemap: this.options.sourcemap ? "inline" : false,
+        plugins: [this.externalizePlugin],
+        logLevel: this.options.silent ? "silent" : "info"
+      });
+      compiled.set(entryFile, result.outputFiles[0].text);
+    }
+    return {
+      compiled
+    };
+  }
+  /**
+   * Compile source code from memory (no disk I/O required)
+   * @param sourceCode - The source code string to compile
+   * @param virtualPath - A virtual file path for the source (used for resolve directory and loader detection)
+   * @returns The compiled code string
+   */
+  async compileFromSource(sourceCode, virtualPath) {
+    invariant(sourceCode, "Source code not provided");
+    invariant(virtualPath, "Virtual path not provided");
+    const ext = virtualPath.split(".").pop()?.toLowerCase();
+    const loader = ext === "ts" ? "ts" : ext === "tsx" ? "tsx" : ext === "jsx" ? "jsx" : "js";
+    const result = await esbuild.build({
+      stdin: {
+        contents: sourceCode,
+        resolveDir: process.cwd(),
+        sourcefile: virtualPath,
+        loader
+      },
+      bundle: true,
+      write: false,
+      // Output as IIFE (Immediately Invoked Function Expression) so it can be
+      // executed with vm.Script in a sandboxed context. The globalName specifies
+      // which variable the exports are assigned to: var __exports = (() => { ... })();
+      format: "iife",
+      globalName: "__exports",
+      platform: "node",
+      target: "node20",
+      minify: this.options.minify,
+      sourcemap: this.options.sourcemap ? "inline" : false,
+      plugins: [this.externalizePlugin],
+      logLevel: this.options.silent ? "silent" : "info"
+    });
+    return result.outputFiles[0].text;
+  }
+};
+
+// src/runtime/vm.ts
+import { Script, createContext } from "node:vm";
+import { createRequire } from "node:module";
+var buildGlobals = () => Object.fromEntries(
+  Object.getOwnPropertyNames(globalThis).map((key) => [
+    key,
+    globalThis[key]
+  ])
+);
+async function executeEsm(code) {
+  const requireResolutionRoot = `${process.cwd()}/`;
+  const script = new Script(`${code}
+__exports;`);
+  const sandbox = createContext({
+    ...buildGlobals(),
+    require: createRequire(requireResolutionRoot),
+    // Provide CommonJS-style globals for bundled dependencies that expect them
+    // (e.g., node-cron uses __dirname for its daemon path)
+    __dirname: process.cwd(),
+    __filename: `${process.cwd()}/vm-script.js`
+  });
+  return script.runInContext(sandbox);
+}
+
+// src/runtime/task.ts
+import invariant5 from "tiny-invariant";
+
+// src/source/entry.ts
+import invariant4 from "tiny-invariant";
+
+// src/source/entryLiveSource.ts
+import { createHash } from "node:crypto";
+import invariant2 from "tiny-invariant";
+var EntryLiveSource = class {
+  _code;
+  codeMd5Hash = null;
+  onTaskCodeLoaded;
+  paths;
+  _fileDescriptor;
+  _tasksRootDir;
+  constructor(options, config) {
+    invariant2(options.livePath, "Live task path not provided");
+    invariant2(options.code, "Code not provided");
+    this._code = options.code;
+    this.paths = {
+      compiled: options.livePath,
+      source: options.livePath,
+      relativeEntry: "",
+      relativeParent: ""
+    };
+    this._fileDescriptor = {
+      type: "file",
+      path: {
+        absolute: options.livePath,
+        relative: options.livePath,
+        parent: {
+          absolute: "",
+          relative: ""
+        }
+      },
+      ext: ".ts",
+      filename: options.livePath,
+      filenameNoExt: options.livePath.replace(/\.[^.]+$/, "")
+    };
+    this._tasksRootDir = "";
+    this.onTaskCodeLoaded = config.onTaskCodeLoaded;
+  }
+  get path() {
+    return this.paths;
+  }
+  get fileDescriptor() {
+    return this._fileDescriptor;
+  }
+  get tasksRootDir() {
+    return this._tasksRootDir;
+  }
+  get codeHash() {
+    return this.codeMd5Hash;
+  }
+  get code() {
+    return this._code;
+  }
+  async load() {
+    if (this.isLoaded()) {
+      return this.codeMd5Hash;
+    }
+    this.codeMd5Hash = createHash("md5").update(this.code).digest("hex");
+    console.log(`Loading live task from: ${this.paths.compiled}, hash: ${this.codeMd5Hash}`);
+    console.log("Code hash:", this.codeMd5Hash);
+    this.onTaskCodeLoaded?.(this.codeMd5Hash);
+    return this.codeMd5Hash;
+  }
+  isLoaded() {
+    return Boolean(this.code && this.codeMd5Hash);
+  }
+};
+
+// src/source/entryDbSource.ts
+import { createHash as createHash2 } from "node:crypto";
+import invariant3 from "tiny-invariant";
+var EntryDbSource = class {
+  _code;
+  codeMd5Hash = null;
+  onTaskCodeLoaded;
+  paths;
+  _fileDescriptor;
+  _tasksRootDir;
+  constructor(options, config) {
+    invariant3(options.compiledCode, "Compiled code not provided");
+    invariant3(options.descriptor, "File descriptor not provided");
+    invariant3(options.tasksRootDir, "Tasks root directory not provided");
+    this._code = options.compiledCode;
+    this._fileDescriptor = options.descriptor;
+    this._tasksRootDir = options.tasksRootDir;
+    this.paths = {
+      // Source path is the original TypeScript file
+      source: options.descriptor.path.absolute,
+      // Compiled path is no longer a file path - we use the relative entry as identifier
+      compiled: options.descriptor.path.relative,
+      relativeEntry: options.descriptor.path.relative,
+      relativeParent: options.descriptor.path.parent.relative
+    };
+    this.onTaskCodeLoaded = config.onTaskCodeLoaded;
+  }
+  get path() {
+    return this.paths;
+  }
+  get fileDescriptor() {
+    return this._fileDescriptor;
+  }
+  get tasksRootDir() {
+    return this._tasksRootDir;
+  }
+  get codeHash() {
+    return this.codeMd5Hash;
+  }
+  get code() {
+    return this._code;
+  }
+  async load() {
+    if (this.isLoaded()) {
+      return this.codeMd5Hash;
+    }
+    this.codeMd5Hash = createHash2("md5").update(this._code).digest("hex");
+    this.onTaskCodeLoaded?.(this.codeMd5Hash);
+    return this.codeMd5Hash;
+  }
+  isLoaded() {
+    return Boolean(this._code && this.codeMd5Hash);
+  }
+};
+
+// src/source/util.ts
+function isLiveSourceParams(params) {
+  return "livePath" in params && "code" in params;
+}
+function isDbSourceParams(params) {
+  return "compiledCode" in params && "descriptor" in params;
+}
+
+// src/source/entry.ts
+var Entry = class {
+  entry;
+  callbacks;
+  constructor(options, config) {
+    this.callbacks = {
+      onTaskCodeLoaded: config.onTaskCodeLoaded ?? void 0
+    };
+    if (isLiveSourceParams(options)) {
+      this.entry = new EntryLiveSource(options, config);
+    } else if (isDbSourceParams(options)) {
+      this.entry = new EntryDbSource(options, config);
+    } else {
+      throw new TypeError("Invalid source parameters");
+    }
+  }
+  async load() {
+    return this.entry.load();
+  }
+  isLoaded() {
+    return this.entry.isLoaded();
+  }
+  async getExports() {
+    invariant4(this.entry.code, "Entry code not loaded. Load entry first.");
+    try {
+      const taskExports = await executeEsm(this.entry.code);
+      this.callbacks.onTaskCodeLoaded?.(this.entry.codeHash);
+      let taskFunction;
+      if (typeof taskExports.default === "function") {
+        taskFunction = taskExports.default;
+      } else if (taskExports.default && typeof taskExports.default === "object" && "task" in taskExports.default) {
+        taskFunction = taskExports.default.task;
+      } else {
+        taskFunction = taskExports.task;
+      }
+      return {
+        task: taskFunction,
+        timing: taskExports.timing,
+        shouldSkip: taskExports.shouldSkip,
+        shouldRetry: taskExports.shouldRetry,
+        onSuccess: taskExports.onSuccess,
+        onError: taskExports.onError,
+        onComplete: taskExports.onComplete
+      };
+    } catch (error) {
+      console.error("Error getting task exports:", error);
+      return null;
+    }
+  }
+  get paths() {
+    return this.entry.path;
+  }
+  get fileDescriptor() {
+    return this.entry.fileDescriptor;
+  }
+  get tasksRootDir() {
+    return this.entry.tasksRootDir;
+  }
+  get codeHash() {
+    return this.entry.codeHash;
+  }
+  get code() {
+    return this.entry.code;
+  }
+};
+
+// src/runtime/task.ts
+var Task = class {
+  taskCallbacks;
+  runtimeCallbacks;
+  env;
+  kv;
+  log;
+  timing;
+  sqlite;
+  meta;
+  entry = null;
+  entryExports = null;
+  constructor({
+    entryParams,
+    buildConfigFn
+  }) {
+    invariant5(entryParams, "Entry params not provided! Cannot create task.");
+    this.entry = new Entry(entryParams, {
+      onTaskCodeLoaded: this.taskCallbacks?.onTaskCodeLoaded
+    });
+    const { taskCallbacks, runtimeCallbacks, env, kv, log, timing, sqlite } = buildConfigFn({
+      sourcePath: this.entry.paths.source,
+      compiledPath: this.entry.paths.compiled
+    });
+    this.taskCallbacks = taskCallbacks;
+    this.runtimeCallbacks = runtimeCallbacks;
+    this.sqlite = sqlite;
+    this.meta = {
+      fileTaskId: -1,
+      fileTaskVersionId: -1,
+      file: this.entry.fileDescriptor,
+      tasksRootDir: this.entry.tasksRootDir
+    };
+    this.env = env;
+    this.kv = kv;
+    this.log = log;
+    this.timing = timing;
+  }
+  get sourcePath() {
+    invariant5(this.entry, "Entry not initialized.");
+    return this.entry.paths.source;
+  }
+  get compiledPath() {
+    invariant5(this.entry, "Entry not initialized.");
+    return this.entry.paths.compiled;
+  }
+  /**
+   * Unique identifier for the task - the relative entry path
+   */
+  get taskPath() {
+    invariant5(this.entry, "Entry not initialized.");
+    return this.entry.paths.relativeEntry;
+  }
+  get codeHash() {
+    invariant5(this.entry, "Entry not initialized.");
+    return this.entry.codeHash;
+  }
+  get timingPattern() {
+    invariant5(this.entryExports, "Entry exports not initialized.");
+    return this.entryExports.timing;
+  }
+  hasTaskExport() {
+    return this.entryExports?.task !== void 0;
+  }
+  hasTimingExport() {
+    return this.entryExports?.timing !== void 0;
+  }
+  async loadEntry() {
+    invariant5(this.entry, "Entry not initialized.");
+    await this.entry.load();
+    this.entryExports = await this.entry.getExports();
+  }
+  async execute() {
+    invariant5(this.entry, "Entry not initialized.");
+    try {
+      await this.loadEntry();
+      invariant5(this.entry.isLoaded(), "Entry failed to load.");
+      invariant5(this.entryExports, "Entry failed to get exports.");
+      this.taskCallbacks?.onTaskExportsLoaded?.();
+      const loadResult = await this.taskCallbacks?.onTaskLoadComplete?.({
+        paths: this.entry.paths,
+        md5Hash: this.entry.codeHash,
+        compiledCode: this.entry.code
+      });
+      this.meta.fileTaskId = loadResult?.fileTaskId ?? -1;
+      this.meta.fileTaskVersionId = loadResult?.fileTaskVersionId ?? -1;
+    } catch (error) {
+      if (this.entry.paths.relativeEntry) {
+        await this.runtimeCallbacks?.onFailure?.({
+          path: this.entry.paths.relativeEntry
+        });
+      }
+      throw error;
+    }
+    await this.taskCallbacks?.onTaskExecutionStart?.();
+    const {
+      shouldSkip,
+      // shouldRetry,
+      onSuccess,
+      onError,
+      onComplete,
+      task
+    } = this.entryExports;
+    if (!task) {
+      await this.runtimeCallbacks?.onNotFound?.({
+        path: this.entry.paths.relativeEntry
+      });
+      throw new Error("Task function not found");
+    }
+    const taskContext = {
+      env: this.env,
+      meta: this.meta,
+      kv: this.kv,
+      log: this.log,
+      timing: this.timing,
+      sqlite: this.sqlite
+    };
+    if (await shouldSkip?.(taskContext)) {
+      await this.runtimeCallbacks?.onSkip?.({
+        path: this.entry.paths.relativeEntry
+      });
+      return;
+    }
+    try {
+      await this.runtimeCallbacks?.onStart?.({
+        path: this.entry.paths.relativeEntry
+      });
+      const taskReturnValue = await task(taskContext);
+      await this.runtimeCallbacks?.onSuccess?.({
+        path: this.entry.paths.relativeEntry
+      });
+      await onSuccess?.(taskContext);
+      return taskReturnValue;
+    } catch (err) {
+      await this.runtimeCallbacks?.onFailure?.({
+        path: this.entry.paths.relativeEntry
+      });
+      await onError?.(err, taskContext);
+      throw err;
+    } finally {
+      await onComplete?.(taskContext);
+    }
+  }
+};
+
+// src/runtime/taskLibrary.ts
+import invariant6 from "tiny-invariant";
+var TaskLibrary = class {
+  tasks;
+  constructor() {
+    this.tasks = /* @__PURE__ */ new Map();
+  }
+  add(taskOrTasks) {
+    if (Array.isArray(taskOrTasks)) {
+      taskOrTasks.forEach((task) => this.tasks.set(task.taskPath, task));
+    } else {
+      this.tasks.set(taskOrTasks.taskPath, taskOrTasks);
+    }
+  }
+  remove(taskPath) {
+    if (Array.isArray(taskPath)) {
+      taskPath.forEach((task) => this.tasks.delete(task.taskPath));
+    } else {
+      this.tasks.delete(taskPath);
+    }
+  }
+  /**
+   * Add tasks from in-memory compiled code (stored in DB)
+   */
+  addFromCompiledCode({
+    compiledCode,
+    descriptors,
+    tasksRootDir,
+    buildConfigFn
+  }) {
+    compiledCode.forEach((code, sourcePath) => {
+      const descriptor = descriptors[sourcePath];
+      if (!descriptor) {
+        console.warn(`No descriptor found for source path: ${sourcePath}`);
+        return;
+      }
+      const task = new Task({
+        buildConfigFn,
+        entryParams: {
+          compiledCode: code,
+          descriptor,
+          tasksRootDir
+        }
+      });
+      this.tasks.set(task.taskPath, task);
+    });
+  }
+  async execute(taskPath) {
+    const task = this.tasks.get(taskPath);
+    invariant6(task, `Task not found for path: ${taskPath}`);
+    return task.execute();
+  }
+  getTasks() {
+    return Array.from(this.tasks.values());
+  }
+};
+
+// src/runtime/taskLibraryScheduler.ts
+import { validate, schedule } from "node-cron";
+import invariant7 from "tiny-invariant";
+import { logTaskLibraryScheduler, logTaskLibrarySchedulerError } from "@apisurf/ngn-os";
+var TaskLibraryScheduler = class {
+  taskLibrary;
+  scheduledTasks = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.taskLibrary = options.taskLibrary;
+  }
+  async start() {
+    logTaskLibraryScheduler("Starting scheduler");
+    const scheduledTasks = this.taskLibrary.getTasks().map(async (task) => {
+      try {
+        const res = await this.scheduleTask(task);
+        return res;
+      } catch (error) {
+        logTaskLibrarySchedulerError(`Error scheduling task: ${task.taskPath}`);
+        logTaskLibrarySchedulerError(error);
+      }
+    });
+    await Promise.all(scheduledTasks);
+    logTaskLibraryScheduler("Scheduler started");
+  }
+  async stop() {
+    logTaskLibraryScheduler("Stopping scheduler");
+    for (const [path, task] of this.scheduledTasks) {
+      logTaskLibraryScheduler(`Stopping scheduled task: ${path}`);
+      task.stop();
+    }
+  }
+  async scheduleTask(task) {
+    logTaskLibraryScheduler(`Scheduling task: ${task.taskPath}`);
+    await task.loadEntry();
+    logTaskLibraryScheduler(`Scheduling: ${task.taskPath} with pattern: ${task.timingPattern}`);
+    invariant7(task.hasTimingExport(), `timing pattern is missing for ${task.taskPath}`);
+    invariant7(task.hasTaskExport(), `task function is missing for ${task.taskPath}`);
+    invariant7(
+      task.timingPattern && this.isCronPatternValid(task.timingPattern),
+      `Invalid cron pattern: ${task.timingPattern} for ${task.taskPath}`
+    );
+    const wrappedUserTask = async () => task.execute();
+    const scheduledTask = schedule(task.timingPattern, wrappedUserTask);
+    this.scheduledTasks.set(task.taskPath, scheduledTask);
+    logTaskLibraryScheduler(`Scheduled: ${task.taskPath}`);
+  }
+  unscheduleTask(task) {
+    const existingTask = this.scheduledTasks.get(task.taskPath);
+    if (!existingTask) {
+      return;
+    }
+    logTaskLibraryScheduler(`Unscheduling: ${task.taskPath}`);
+    existingTask.stop();
+    this.scheduledTasks.delete(task.taskPath);
+    logTaskLibraryScheduler(`Unscheduled: ${task.taskPath}`);
+  }
+  isCronPatternValid(cronPattern) {
+    return validate(cronPattern);
+  }
+  // startScheduledTask(path: string) {
+  //   const task = this.scheduledTasks.get(path);
+  //   if (!task) {
+  //     return;
+  //   }
+  //   task.start();
+  // }
+  // stopScheduledTask(path: string) {
+  //   const task = this.scheduledTasks.get(path);
+  //   if (!task) {
+  //     return;
+  //   }
+  //   task.stop();
+  // }
+};
+
+// src/runtime/taskOnceRunner.ts
+import invariant8 from "tiny-invariant";
+import { logTaskOnceRunner, logTaskOnceRunnerError } from "@apisurf/ngn-os";
+var TaskOnceRunner = class {
+  task;
+  constructor(options) {
+    this.task = options.task;
+  }
+  async run() {
+    logTaskOnceRunner(`Preparing to run task: ${this.task.taskPath}`);
+    await this.task.loadEntry();
+    logTaskOnceRunner(`Loaded task code: ${this.task.taskPath}`);
+    invariant8(this.task.hasTaskExport(), `task function is missing for ${this.task.taskPath}`);
+    logTaskOnceRunner(`Running task: ${this.task.taskPath}`);
+    try {
+      await this.task.execute();
+      logTaskOnceRunner(`Task completed: ${this.task.taskPath}`);
+    } catch (error) {
+      logTaskOnceRunnerError(`Error running task: ${this.task.taskPath}`);
+      logTaskOnceRunnerError(error);
+      throw error;
+    }
+  }
+};
+
+// src/db/db.ts
+import {
+  safeInitDbClient,
+  initDbFileIfNotExists,
+  isDbPath
+} from "@apisurf/ngn-persistence";
+import invariant9 from "tiny-invariant";
+var db;
+async function setupDbClient(dbPath) {
+  invariant9(isDbPath(dbPath), "Invalid db path");
+  if (db) {
+    return db;
+  }
+  db = await safeInitDbClient(dbPath);
+  return db;
+}
+function getDbClient() {
+  invariant9(db, "DB client not initialized");
+  return db;
+}
+
+// src/runtime/generateControls.ts
+import {
+  logTaskCallback,
+  logTaskConsoleError,
+  logTaskConsoleInfo,
+  logTaskConsoleWarn
+} from "@apisurf/ngn-os";
+import invariant10 from "tiny-invariant";
+
+// src/runtime/taskSqlite.ts
+import { mkdirSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, resolve, sep } from "node:path";
+import {
+  openDbClient
+} from "@apisurf/ngn-persistence";
+var openClients = /* @__PURE__ */ new Map();
+async function runMigrations(client, migrations) {
+  if (!migrations.length) return;
+  await client.execute(`
+    CREATE TABLE IF NOT EXISTS _ngn_migrations (
+      id TEXT PRIMARY KEY,
+      applied_at TEXT NOT NULL
+    )
+  `);
+  const applied = await client.execute("SELECT id FROM _ngn_migrations");
+  const appliedIds = new Set(applied.rows.map((r) => r.id));
+  for (const migration of migrations) {
+    if (appliedIds.has(migration.id)) continue;
+    await client.execute(migration.up);
+    await client.execute({
+      sql: "INSERT INTO _ngn_migrations (id, applied_at) VALUES (?, ?)",
+      args: [migration.id, (/* @__PURE__ */ new Date()).toISOString()]
+    });
+  }
+}
+function resolveTaskDbPath(taskDir, file) {
+  if (typeof file !== "string" || !file.trim()) {
+    throw new Error("A database file name is required");
+  }
+  const relativePath = file.startsWith("file:") ? file.slice(5) : file;
+  if (!relativePath) {
+    throw new Error("A database file name is required");
+  }
+  if (isAbsolute(relativePath)) {
+    throw new Error(
+      `Database file must be relative to the task folder, got an absolute path: "${file}"`
+    );
+  }
+  const resolved = resolve(taskDir, relativePath);
+  const taskDirRoot = taskDir.endsWith(sep) ? taskDir : `${taskDir}${sep}`;
+  if (!resolved.startsWith(taskDirRoot)) {
+    throw new Error(
+      `Database file "${file}" resolves outside the task folder (${taskDir}). A task can only manage databases in its own folder.`
+    );
+  }
+  return resolved;
+}
+function getClient(absolutePath) {
+  const existing = openClients.get(absolutePath);
+  if (existing) {
+    return existing;
+  }
+  mkdirSync(dirname(absolutePath), { recursive: true });
+  const client = openDbClient(`file:${absolutePath}`);
+  openClients.set(absolutePath, client);
+  return client;
+}
+function closeClient(absolutePath) {
+  const client = openClients.get(absolutePath);
+  if (client) {
+    client.close();
+    openClients.delete(absolutePath);
+  }
+}
+function createTaskSqlite(taskSourcePath) {
+  const taskDir = dirname(taskSourcePath);
+  const defaultDbPath = join(taskDir, `${basename(taskSourcePath, extname(taskSourcePath))}.db`);
+  const defaultClient = () => getClient(defaultDbPath);
+  return {
+    get client() {
+      return defaultClient();
+    },
+    get path() {
+      return defaultDbPath;
+    },
+    execute: (sql, args) => defaultClient().execute(args ? { sql, args } : sql),
+    batch: (statements) => defaultClient().batch(statements),
+    async initDB(options) {
+      const dbPath = resolveTaskDbPath(taskDir, options.file);
+      const client = getClient(dbPath);
+      if (options.migrations?.length) {
+        await runMigrations(client, options.migrations);
+      }
+      return {
+        client,
+        path: dbPath,
+        execute: (sql, args) => client.execute(args ? { sql, args } : sql),
+        batch: (statements) => client.batch(statements),
+        close: () => closeClient(dbPath)
+      };
+    },
+    async destroyDB(file) {
+      const dbPath = resolveTaskDbPath(taskDir, file);
+      closeClient(dbPath);
+      await unlink(dbPath);
+    }
+  };
+}
+function closeTaskDatabases() {
+  for (const client of openClients.values()) {
+    client.close();
+  }
+  openClients.clear();
+}
+
+// src/db/services/fileTask.ts
+import { $fileTaskInsert } from "@apisurf/ngn-schema";
+var FileTaskService = class {
+  constructor(db2) {
+    this.db = db2;
+  }
+  async add(task) {
+    const { path, status } = $fileTaskInsert.parse(task);
+    const sql = `
+      INSERT INTO file_tasks (path, parent_path, status)
+      VALUES (:path, :parentPath, :status)
+    `;
+    return this.db.execute({
+      sql,
+      args: { path, parentPath: task.parent_path, status }
+    });
+  }
+  async del(id) {
+    return this.db.execute({
+      sql: "DELETE FROM file_tasks WHERE id = :id",
+      args: { id }
+    });
+  }
+  async getByPath(path) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT * FROM file_tasks WHERE path = :path LIMIT 1",
+      args: { path }
+    });
+    return rows[0];
+  }
+  async list() {
+    const { rows } = await this.db.execute("SELECT * FROM file_tasks LIMIT 1000");
+    return rows;
+  }
+  async bumpUpdatedAt(id) {
+    return this.db.execute({
+      sql: "UPDATE file_tasks SET updated_at = :updatedAt WHERE id = :id",
+      args: { updatedAt: (/* @__PURE__ */ new Date()).valueOf(), id }
+    });
+  }
+  async updateStatus(id, status) {
+    return this.db.execute({
+      sql: "UPDATE file_tasks SET status = :status WHERE id = :id",
+      args: { status, id }
+    });
+  }
+};
+
+// src/db/services/fileTaskVersion.ts
+import { $fileTaskVersion } from "@apisurf/ngn-schema";
+var $fileTaskVersionInsert = $fileTaskVersion.omit({
+  id: true,
+  created_at: true
+});
+var FileTaskVersionService = class {
+  constructor(db2) {
+    this.db = db2;
+  }
+  async add(taskVersion) {
+    const { file_task_id, md5_hash, version, compiled_code } = $fileTaskVersionInsert.parse(taskVersion);
+    const sql = `
+      INSERT INTO file_task_versions (file_task_id, md5_hash, version, compiled_code)
+      VALUES (:file_task_id, :md5_hash, :version, :compiled_code)
+    `;
+    return this.db.execute({
+      sql,
+      args: { file_task_id, md5_hash, version, compiled_code }
+    });
+  }
+  async getByHash(hash, file_task_id) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT * FROM file_task_versions WHERE md5_hash = :md5_hash AND file_task_id = :file_task_id ORDER BY version DESC LIMIT 1",
+      args: { md5_hash: hash, file_task_id }
+    });
+    return rows[0];
+  }
+  async getByVersion(version, file_task_id) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT * FROM file_task_versions WHERE version = :version AND file_task_id = :file_task_id LIMIT 1",
+      args: { version, file_task_id }
+    });
+    return rows[0];
+  }
+  async getLastVersion(file_task_id) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT MAX(version) as version FROM file_task_versions WHERE file_task_id = :file_task_id",
+      args: { file_task_id }
+    });
+    return rows[0]?.version ?? 0;
+  }
+  async getById(id) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT * FROM file_task_versions WHERE id = :id LIMIT 1",
+      args: { id }
+    });
+    return rows[0];
+  }
+  async getCompiledCode(id) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT compiled_code FROM file_task_versions WHERE id = :id LIMIT 1",
+      args: { id }
+    });
+    return rows[0]?.compiled_code;
+  }
+};
+
+// src/db/services/registerTask.ts
+async function registerFileTask(dbClient, md5Hash, compiledCode, paths) {
+  const fileTaskVersionService = new FileTaskVersionService(dbClient);
+  const fileTaskService = new FileTaskService(dbClient);
+  const previousFileTask = await fileTaskService.getByPath(paths.relativeEntry);
+  if (!previousFileTask) {
+    await fileTaskService.add({
+      path: paths.relativeEntry,
+      parent_path: paths.relativeParent,
+      status: "active"
+    });
+  } else {
+    await fileTaskService.updateStatus(previousFileTask.id, "active");
+  }
+  const fileTask = await fileTaskService.getByPath(paths.relativeEntry);
+  if (!fileTask) {
+    throw new Error("Could not create file task in DB.");
+  }
+  const lastVersionNumber = await fileTaskVersionService.getLastVersion(fileTask.id);
+  if (!lastVersionNumber) {
+    await fileTaskVersionService.add({
+      file_task_id: fileTask.id,
+      md5_hash: md5Hash,
+      compiled_code: compiledCode,
+      version: 1
+    });
+    await fileTaskService.bumpUpdatedAt(fileTask.id);
+  } else {
+    const lastVersion = await fileTaskVersionService.getByVersion(lastVersionNumber, fileTask.id);
+    if (lastVersion.md5_hash !== md5Hash) {
+      const nextVersionNumber = lastVersionNumber + 1;
+      await fileTaskVersionService.add({
+        version: nextVersionNumber,
+        file_task_id: fileTask.id,
+        md5_hash: md5Hash,
+        compiled_code: compiledCode
+      });
+      await fileTaskService.bumpUpdatedAt(fileTask.id);
+    }
+  }
+  const version = await fileTaskVersionService.getByHash(md5Hash, fileTask.id);
+  if (!version) {
+    throw new Error("Could not create file task version in DB.");
+  }
+  return {
+    fileTaskId: fileTask.id,
+    fileVersionId: version.id,
+    compiledCode: version.compiled_code
+  };
+}
+
+// src/db/services/taskRun.ts
+var TaskRunService = class {
+  constructor(db2) {
+    this.db = db2;
+  }
+  async initTaskRun(data) {
+    const { rows } = await this.db.execute({
+      sql: "INSERT INTO task_runs (file_task_id, file_task_version_id, status) VALUES (:file_task_id, :file_task_version_id, 'pending') RETURNING id",
+      args: {
+        file_task_id: data.file_task_id,
+        file_task_version_id: data.file_task_version_id
+      }
+    });
+    return rows[0].id;
+  }
+  async skipTaskRun(taskRunId) {
+    await this.db.execute({
+      sql: "UPDATE task_runs SET status = 'skipped', ended_at = :ended_at WHERE id = :id",
+      args: { id: taskRunId, ended_at: Date.now() }
+    });
+  }
+  async startTaskRun(taskRunId) {
+    await this.db.execute({
+      sql: "UPDATE task_runs SET started_at = :started_at, status = 'running' WHERE id = :id",
+      args: {
+        started_at: Date.now(),
+        id: taskRunId
+      }
+    });
+  }
+  async endTaskRun(taskRunId, status) {
+    await this.db.execute({
+      sql: "UPDATE task_runs SET ended_at = :ended_at, status = :status WHERE id = :id",
+      args: {
+        ended_at: Date.now(),
+        status,
+        id: taskRunId
+      }
+    });
+  }
+  async getById(taskId) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT * FROM task_runs WHERE id = :taskId",
+      args: { taskId }
+    });
+    return rows[0];
+  }
+  async listByTaskVersion(fileTaskId, fileTaskVersionId) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT * FROM task_runs WHERE file_task_id = :fileTaskId AND file_task_version_id = :fileTaskVersionId ORDER BY started_at DESC LIMIT 100",
+      args: { fileTaskId, fileTaskVersionId }
+    });
+    return rows;
+  }
+};
+
+// src/db/services/log.ts
+var LogService = class {
+  constructor(db2) {
+    this.db = db2;
+  }
+  async logInfo(fileTaskId, taskRunId, value) {
+    return this.add(fileTaskId, taskRunId, "info", value);
+  }
+  async logWarning(fileTaskId, taskRunId, value) {
+    return this.add(fileTaskId, taskRunId, "warning", value);
+  }
+  async logError(fileTaskId, taskRunId, value) {
+    return this.add(fileTaskId, taskRunId, "error", value);
+  }
+  async add(fileTaskId, taskRunId, status, value) {
+    const { rows } = await this.db.execute({
+      sql: "INSERT INTO logs (file_task_id, task_run_id, status, value) VALUES (:fileTaskId, :taskRunId, :status, :value) RETURNING id",
+      args: { fileTaskId, taskRunId, status, value }
+    });
+    return rows[0].id;
+  }
+};
+
+// src/db/services/kv.ts
+function normalizeValue(value) {
+  if (typeof value !== "string") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      try {
+        return value?.toString() ?? null;
+      } catch (error) {
+        console.error("Error setting key-value pair in db", error);
+        return null;
+      }
+    }
+  } else {
+    return value;
+  }
+}
+var KVService = class {
+  constructor(db2) {
+    this.db = db2;
+  }
+  async getValue(fileTaskId, key) {
+    const { rows } = await this.db.execute({
+      sql: "SELECT * FROM kvs WHERE file_task_id = :fileTaskId AND key = :key LIMIT 1",
+      args: { fileTaskId, key }
+    });
+    return rows[0]?.value;
+  }
+  async setValue(fileTaskId, key, value) {
+    const existingValue = await this.getValue(fileTaskId, key);
+    const normalizedValue = normalizeValue(value);
+    if (existingValue) {
+      return this.db.execute({
+        sql: "UPDATE kvs SET value = :value WHERE file_task_id = :fileTaskId AND key = :key",
+        args: { fileTaskId, key, value: normalizedValue }
+      });
+    }
+    return this.db.execute({
+      sql: "INSERT INTO kvs (file_task_id, key, value) VALUES (:fileTaskId, :key, :value)",
+      args: { fileTaskId, key, value: normalizedValue }
+    });
+  }
+  async deleteValue(fileTaskId, key) {
+    return this.db.execute({
+      sql: "DELETE FROM kvs WHERE file_task_id = :fileTaskId AND key = :key",
+      args: { fileTaskId, key }
+    });
+  }
+};
+
+// src/db/services/timing.ts
+var TimingService = class {
+  constructor(db2) {
+    this.db = db2;
+  }
+  start(file_task_id, task_run_id, label) {
+    const startTime = Date.now();
+    const stopAndRecordCb = async () => {
+      const endTime = Date.now();
+      const duration = endTime - startTime;
+      await this.db.execute({
+        sql: "INSERT INTO timings (label, value, file_task_id, task_run_id) VALUES (:label, :value, :file_task_id, :task_run_id) RETURNING id",
+        args: { label, value: duration, file_task_id, task_run_id }
+      });
+      return;
+    };
+    return stopAndRecordCb;
+  }
+};
+
+// src/runtime/generateControls.ts
+function createControlsGenerator({
+  dbClient,
+  env
+}) {
+  const taskRunService = new TaskRunService(dbClient);
+  const logService = new LogService(dbClient);
+  const kvService = new KVService(dbClient);
+  const timingService = new TimingService(dbClient);
+  const generateControls = ({ sourcePath, compiledPath }) => {
+    let fileTaskId;
+    let fileTaskVersionId;
+    let fileTaskRunId;
+    const assertMandatoryIds = () => {
+      invariant10(!!fileTaskId, "Task ID not found");
+      invariant10(!!fileTaskVersionId, "Task version ID not found");
+    };
+    const taskCallbacks = {
+      async onTaskLoadComplete({ paths, md5Hash, compiledCode }) {
+        const result = await registerFileTask(dbClient, md5Hash, compiledCode, {
+          relativeEntry: paths.relativeEntry,
+          relativeParent: paths.relativeParent
+        });
+        fileTaskId = result.fileTaskId;
+        fileTaskVersionId = result.fileVersionId;
+        return {
+          fileTaskId,
+          fileTaskVersionId
+        };
+      },
+      async onTaskExecutionStart() {
+        assertMandatoryIds();
+        fileTaskRunId = await taskRunService.initTaskRun({
+          file_task_id: fileTaskId,
+          file_task_version_id: fileTaskVersionId
+        });
+      },
+      async onTaskCodeLoaded() {
+      },
+      async onTaskExportsLoaded() {
+      }
+    };
+    const runtimeCallbacks = {
+      async onNotFound() {
+        assertMandatoryIds();
+        await logService.logError(fileTaskId, fileTaskRunId, "Task not found");
+        logTaskCallback(`Task not found: ${fileTaskId}, run ID: ${fileTaskRunId}`);
+      },
+      async onSkip() {
+        assertMandatoryIds();
+        await taskRunService.skipTaskRun(fileTaskRunId);
+        await logService.logInfo(fileTaskId, fileTaskRunId, "Task skipped");
+        logTaskCallback(`Task skipped: ${fileTaskId}, run ID: ${fileTaskRunId}`);
+      },
+      async onStart() {
+        assertMandatoryIds();
+        await taskRunService.startTaskRun(fileTaskRunId);
+        await logService.logInfo(fileTaskId, fileTaskRunId, "Task started");
+        logTaskCallback(`Task started: ${fileTaskId}, run ID: ${fileTaskRunId}`);
+      },
+      async onFailure() {
+        assertMandatoryIds();
+        await taskRunService.endTaskRun(fileTaskRunId, "failure");
+        await logService.logError(fileTaskId, fileTaskRunId, "Task failed");
+        logTaskCallback(`Task failed: ${fileTaskId}, run ID: ${fileTaskRunId}`);
+      },
+      async onSuccess() {
+        assertMandatoryIds();
+        await taskRunService.endTaskRun(fileTaskRunId, "success");
+        await logService.logInfo(fileTaskId, fileTaskRunId, "Task succeeded");
+        logTaskCallback(`Task succeeded: ${fileTaskId}, run ID: ${fileTaskRunId}`);
+      }
+    };
+    return {
+      compiledPath,
+      sourcePath,
+      taskCallbacks,
+      runtimeCallbacks,
+      env,
+      // Scoped to this task's own folder — see createTaskSqlite
+      sqlite: createTaskSqlite(sourcePath),
+      kv: {
+        async set(key, value) {
+          await kvService.setValue(fileTaskId, key, value);
+        },
+        async get(key) {
+          return kvService.getValue(fileTaskId, key);
+        },
+        async delete(key) {
+          await kvService.deleteValue(fileTaskId, key);
+        }
+      },
+      log: {
+        async info(value) {
+          logTaskConsoleInfo(value);
+          await logService.logInfo(fileTaskId, fileTaskRunId, value);
+        },
+        async error(value) {
+          logTaskConsoleError(value);
+          await logService.logError(fileTaskId, fileTaskRunId, value);
+        },
+        async warning(value) {
+          logTaskConsoleWarn(value);
+          await logService.logWarning(fileTaskId, fileTaskRunId, value);
+        }
+      },
+      timing: {
+        start(label) {
+          return timingService.start(fileTaskId, fileTaskRunId, label);
+        }
+      }
+    };
+  };
+  return generateControls;
+}
+export {
+  Compiler,
+  Task,
+  TaskLibrary,
+  TaskLibraryScheduler,
+  TaskOnceRunner,
+  closeTaskDatabases,
+  createControlsGenerator,
+  executeEsm,
+  getDbClient,
+  initDbFileIfNotExists,
+  setupDbClient
+};