target-supabase-sdk 0.1.8 → 0.1.9

package/src/repo/repo.api.ts

@@ -0,0 +1,50 @@
+import { scanTargetList, validateWithSchema } from "../core.api";
+import { generateResponse, SupabaseResponse } from "../core.interface";
+import { z } from "zod";
+import { CategoryRepo, Repo } from "./repo.interface";
+
+const REPO_USAGE_FIELD = "details->>usage" as const;
+
+export const getScanRemoteRepoValuesSchema = z.object({
+    usage: z.string().trim().min(1),
+});
+
+export type GetScanRemoteRepoValuesPayload = z.infer<typeof getScanRemoteRepoValuesSchema>;
+
+/**
+ * Scan `Repo.value` keys for `category=repo` with matching `details.usage`.
+ * Returns `{ data: string[] }` on success; validation and DB failures use `{ error }` (never throws).
+ */
+export const getScanRemoteRepoValues = async (
+    payload: GetScanRemoteRepoValuesPayload
+): Promise<SupabaseResponse<string[]>> => {
+    try {
+        return await getScanRemoteRepoValuesValidated(payload);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message) as SupabaseResponse<string[]>;
+    }
+};
+
+const getScanRemoteRepoValuesValidated = validateWithSchema(
+    getScanRemoteRepoValuesSchema,
+    "getScanRemoteRepoValuesSchema"
+)(async ({ usage }): Promise<SupabaseResponse<string[]>> => {
+    try {
+        const { data } = await scanTargetList<Repo>({
+            category: CategoryRepo.REPO,
+            selectFields: "value",
+            orderBy: { field: "value", ascending: true },
+            filterList: [{ field: REPO_USAGE_FIELD, operator: "eq", value: usage }],
+        });
+
+        const values = (data ?? [])
+            .map((row) => row.value?.trim())
+            .filter((value): value is string => value != null && value !== "");
+
+        return generateResponse.success([...new Set(values)]);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message) as SupabaseResponse<string[]>;
+    }
+});

package/src/repo/repo.interface.ts

@@ -3,13 +3,15 @@ import { Target } from "../core.interface";
 export enum CategoryRepo {
     /** Project */
     REPO = "repo",
-    SCRIPT = "script",
 }
 
+/** `Repo.details.usage` for task worker remote discovery ({@link registerTasks}). */
+export const TASK_REPO_USAGE = "task";
+
 export interface Repo extends Target {
-    /** Key */
+    /** Human readable name */
     name: string;
-    /** Url */
+    /** Unique key, consumers use this to determine which repo to use */
     value: string;
     details: RepoDetails;
     category: CategoryRepo;
@@ -17,7 +19,13 @@ export interface Repo extends Target {
 
 export interface RepoDetails {
     manifestVersion: number;
-    context?: unknown;
+    /**
+     * Business usage partition for discovery and load (caller-defined string, e.g. `"task"`).
+     * Used by {@link getScanRemoteRepoValues} to narrow scan scope; validity is the caller's responsibility.
+     */
+    usage: string;
+    /** Repo entry module URL or filesystem path — used to dynamic-import TaskRepoContext. */
+    url: string;
     hash: string;
-};
+}
 

package/src/repo/repo.script-loader.ts

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+import { LoggerWithContext } from "../shared/log/log-manager";
+import { resolvePathFromCwd, toFileImportHref } from "../shared/utils/config-path.utils";
+import { TaskRepoScriptRecord } from "../task/task-repo-context";
+import {
+    getScriptLoadKey,
+    LoadedRepoContext,
+    normalizeRepoContextModule,
+} from "./repo-context.utils";
+
+const importedModuleCache = new Map<string, LoadedRepoContext>();
+
+async function importFromFilePath(modulePath: string): Promise<unknown> {
+    return import(toFileImportHref(modulePath));
+}
+
+/** Resolve repo `details.url` to a value suitable for dynamic `import()`. */
+export function resolveRepoEntryHref(url: string, cwd = process.cwd()): string {
+    const trimmed = url.trim();
+    if (trimmed.includes("://")) {
+        return trimmed;
+    }
+    return toFileImportHref(resolvePathFromCwd(cwd, trimmed));
+}
+
+async function importFromSource(source: string, cacheKey: string): Promise<unknown> {
+    const hash = createHash("sha256").update(source).digest("hex").slice(0, 16);
+    const dir = join(tmpdir(), "target-supabase-sdk", "repo-scripts");
+    await mkdir(dir, { recursive: true });
+    const filePath = join(dir, `${cacheKey}-${hash}.mjs`);
+    await writeFile(filePath, source, "utf8");
+    return importFromFilePath(filePath);
+}
+
+export async function loadRepoContextFromScript({
+    logger,
+    script,
+    taskTypeKey,
+}: {
+    logger: LoggerWithContext;
+    script: TaskRepoScriptRecord;
+    taskTypeKey: string;
+}): Promise<LoadedRepoContext | null> {
+    const loadKey = getScriptLoadKey(script);
+    const cacheKey = `${taskTypeKey}@${loadKey}`;
+    const cached = importedModuleCache.get(cacheKey);
+    if (cached != null) {
+        logger.info("命中 Repo 脚本模块缓存", { topic: "repo", context: { cacheKey } });
+        return cached;
+    }
+
+    const { source, modulePath, exportName } = script.details;
+
+    try {
+        let moduleExports: unknown;
+        if (source != null && source.trim() !== "") {
+            logger.info("从 source 动态加载 Repo 脚本", { topic: "repo", context: { scriptId: script.id } });
+            moduleExports = await importFromSource(source, cacheKey);
+        } else if (modulePath != null && modulePath.trim() !== "") {
+            logger.info("从 modulePath 动态加载 Repo 脚本", {
+                topic: "repo",
+                context: { scriptId: script.id, modulePath },
+            });
+            moduleExports = await importFromFilePath(modulePath);
+        } else {
+            logger.warn("脚本缺少 source 或 modulePath", { topic: "repo", context: { scriptId: script.id } });
+            return null;
+        }
+
+        const context = normalizeRepoContextModule(moduleExports, taskTypeKey, exportName);
+        if (context == null) {
+            logger.warn("脚本模块未导出合法的 TaskRepoContext", {
+                topic: "repo",
+                context: { scriptId: script.id, exportName: exportName ?? "default" },
+            });
+            return null;
+        }
+
+        const loaded: LoadedRepoContext = { context, contentHash: loadKey };
+        importedModuleCache.set(cacheKey, loaded);
+        return loaded;
+    } catch (error) {
+        logger.error("动态加载 Repo 脚本失败", {
+            topic: "repo",
+            context: { scriptId: script.id, error: error instanceof Error ? error.message : error },
+        });
+        return null;
+    }
+}
+
+export async function loadRepoContextFromUrl({
+    logger,
+    url,
+    taskTypeKey,
+    exportName,
+}: {
+    logger: LoggerWithContext;
+    url: string;
+    taskTypeKey: string;
+    exportName?: string;
+}): Promise<LoadedRepoContext | null> {
+    const href = resolveRepoEntryHref(url);
+    const cacheKey = `${taskTypeKey}@url:${href}`;
+    const cached = importedModuleCache.get(cacheKey);
+    if (cached != null) {
+        logger.info("命中 Repo URL 模块缓存", { topic: "repo", context: { cacheKey } });
+        return cached;
+    }
+
+    try {
+        logger.info("从 Repo URL 动态加载脚本", { topic: "repo", context: { url, href } });
+        const moduleExports = await import(href);
+        const context = normalizeRepoContextModule(moduleExports, taskTypeKey, exportName);
+        if (context == null) {
+            logger.warn("Repo URL 模块未导出合法的 TaskRepoContext", {
+                topic: "repo",
+                context: { url, exportName: exportName ?? "default" },
+            });
+            return null;
+        }
+        const loaded: LoadedRepoContext = { context, contentHash: cacheKey };
+        importedModuleCache.set(cacheKey, loaded);
+        return loaded;
+    } catch (error) {
+        logger.error("从 Repo URL 动态加载失败", {
+            topic: "repo",
+            context: { url, error: error instanceof Error ? error.message : error },
+        });
+        return null;
+    }
+}
+
+/** Clear in-memory imported module cache (tests / hot reload). */
+export function clearRepoScriptModuleCache(): void {
+    importedModuleCache.clear();
+}

package/src/shared/log/create-api-logger.ts

@@ -0,0 +1,25 @@
+import { logManager, type LogContext, type LoggerWithContext } from "./log-manager";
+
+/**
+ * Options for {@link createApiLogger}.
+ *
+ * - **Core:** optional `traceId` (generated when omitted)
+ * - **Business:** any other {@link LogContext} field (e.g. `nodeId`)
+ */
+export type CreateApiLoggerOptions = {
+    traceId?: string;
+} & Partial<Omit<LogContext, "module" | "traceId">>;
+
+/**
+ * Logger for one SDK API invocation.
+ *
+ * Binds required `module` + optional caller `traceId`; business fields (e.g. `nodeId`) are optional.
+ */
+export function createApiLogger(module: string, options?: CreateApiLoggerOptions): LoggerWithContext {
+    const { traceId, ...businessFields } = options ?? {};
+    return logManager.withContext({
+        module,
+        traceId: traceId ?? logManager.generateTraceId(),
+        ...businessFields,
+    }).logger;
+}

package/src/shared/log/log-manager.ts

@@ -0,0 +1,340 @@
+import { isDevEnvironment } from "../../core.utils";
+import { generateUniqueId } from "../utils/id.utils";
+
+/**
+ * Log severity and semantics (low → high). `minLevel` filters by {@link LOG_LEVEL_RANK}.
+ *
+ * | Level    | Rank | When to use |
+ * |----------|------|-------------|
+ * | DEBUG    | 0    | Diagnostic detail for dev/troubleshooting; noisy, safe to drop in prod. |
+ * | INFO     | 1    | Normal operational flow (startup, polling, state transitions). |
+ * | SUCCESS  | 2    | Positive milestone within a flow (not a separate severity axis — same band as INFO). |
+ * | WARN     | 3    | Recoverable anomaly or degradation; work continues but worth watching. |
+ * | ERROR    | 4    | A concrete operation failed (API, task step, I/O); investigate and retry/fix locally. |
+ * | CRITICAL | 5    | Invariant violated — design flaw, data-integrity risk, or business rule broken; escalate and fix urgently. |
+ */
+enum LogLevel {
+    DEBUG = "DEBUG",
+    INFO = "INFO",
+    SUCCESS = "SUCCESS",
+    WARN = "WARN",
+    ERROR = "ERROR",
+    CRITICAL = "CRITICAL",
+}
+
+const LOG_LEVEL_RANK: Record<LogLevel, number> = {
+    [LogLevel.DEBUG]: 0,
+    [LogLevel.INFO]: 1,
+    [LogLevel.SUCCESS]: 2,
+    [LogLevel.WARN]: 3,
+    [LogLevel.ERROR]: 4,
+    [LogLevel.CRITICAL]: 5,
+};
+
+interface LogEntry {
+    timestamp: number;
+    level: LogLevel;
+    /** Tell people what happened, but more structured */
+    message: string;
+    /** Category of a kind of log */
+    topic: string | null;
+    /** Where the log comes from */
+    module: string;
+    /** Specific process — correlates one logical chain (loop, request). */
+    traceId: string;
+    /** Worker node id when the log is node-scoped; omit for scheduler / admin / API-only paths. */
+    nodeId?: string;
+    extra?: string;
+    context?: unknown;
+}
+
+interface LogContext {
+    module: LogEntry["module"];
+    traceId: LogEntry["traceId"];
+    nodeId?: LogEntry["nodeId"];
+}
+
+type LogRestParams = Omit<LogParams, "message">;
+
+interface LogEntryPayload {
+    message: LogEntry["message"];
+    topic?: LogEntry["topic"];
+    extra?: LogEntry["extra"];
+    context?: LogEntry["context"];
+    level: LogEntry["level"];
+    module: LogEntry["module"];
+    traceId: LogEntry["traceId"];
+    nodeId?: LogEntry["nodeId"];
+}
+
+type LogParams = Pick<LogEntryPayload, "message" | "topic" | "extra" | "context">;
+
+interface LogOptions {
+    defaultTopic: LogEntry["topic"];
+    formatTimestamp: boolean;
+    formatEmoji: boolean;
+    formatPrefix: string;
+    maxHistoryLength: number;
+    /** Logs below this level are skipped. Defaults to DEBUG in dev, INFO in production. */
+    minLevel?: LogLevel;
+    onLog?: (entry: LogEntry) => void;
+}
+
+const DEFAULT_OPTIONS: LogOptions = {
+    defaultTopic: null,
+    formatTimestamp: true,
+    formatEmoji: true,
+    formatPrefix: "",
+    maxHistoryLength: 4096,
+    minLevel: isDevEnvironment() ? LogLevel.DEBUG : LogLevel.INFO,
+};
+
+interface LoggerWithContext {
+    /** Rank 0 — diagnostic detail; dev/troubleshooting only. */
+    debug: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    /** Rank 1 — normal operational flow. */
+    info: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    /** Rank 2 — positive milestone (semantic INFO, not higher severity). */
+    success: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    /** Rank 3 — recoverable anomaly; system continues. */
+    warn: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    /** Rank 4 — a concrete operation failed; needs investigation. */
+    error: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    /** Rank 5 — invariant / design / integrity breach; escalate immediately. */
+    critical: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    /** Merge partial fields into this logger's bound context (e.g. nodeId after register). */
+    resetContext: (fields: Partial<LogContext>) => void;
+}
+
+function mergeLogOptions(options?: Partial<LogOptions>): LogOptions {
+    return { ...DEFAULT_OPTIONS, ...options };
+}
+
+function formatContextValue(value: unknown): string {
+    if (value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return JSON.stringify(value);
+    } catch {
+        return String(value);
+    }
+}
+
+function validateLogContext(logContext: LogContext): void {
+    const missing: string[] = [];
+    if (!logContext.module?.trim()) {
+        missing.push("module");
+    }
+    if (!logContext.traceId?.trim()) {
+        missing.push("traceId");
+    }
+    if (missing.length > 0) {
+        console.warn(`[LogManager] LogContext missing or empty: ${missing.join(", ")}`, logContext);
+    }
+}
+
+class LogManager {
+    private static instance: LogManager;
+    private options: LogOptions;
+    private history: LogEntry[] = [];
+    private readonly levelEmojis = {
+        [LogLevel.DEBUG]: "🔍",
+        [LogLevel.INFO]: "ℹ️",
+        [LogLevel.SUCCESS]: "✅",
+        [LogLevel.WARN]: "⚠️",
+        [LogLevel.ERROR]: "❌",
+        [LogLevel.CRITICAL]: "💀",
+    };
+
+    private constructor(options?: Partial<LogOptions>) {
+        this.options = mergeLogOptions(options);
+    }
+
+    public static getInstance(options?: Partial<LogOptions>): LogManager {
+        if (!LogManager.instance) {
+            LogManager.instance = new LogManager(options);
+        } else if (options != null && Object.keys(options).length > 0) {
+            console.warn("[LogManager] getInstance(options) ignored — singleton already created. Use setOptions() instead.");
+        }
+        return LogManager.instance;
+    }
+
+    public setOptions(options: Partial<LogOptions>): void {
+        this.options = mergeLogOptions({ ...this.options, ...options });
+    }
+
+    public getHistory(): LogEntry[] {
+        return [...this.history];
+    }
+
+    public clearHistory(): void {
+        this.history = [];
+    }
+
+    private getMinLevel(): LogLevel {
+        return this.options.minLevel ?? DEFAULT_OPTIONS.minLevel ?? LogLevel.INFO;
+    }
+
+    private shouldLog(level: LogLevel): boolean {
+        return LOG_LEVEL_RANK[level] >= LOG_LEVEL_RANK[this.getMinLevel()];
+    }
+
+    private createLogEntry({
+        level,
+        message,
+        topic,
+        module,
+        traceId,
+        nodeId,
+        extra,
+        context,
+    }: LogEntryPayload): LogEntry {
+        return {
+            timestamp: Date.now(),
+            level,
+            message,
+            topic: topic === undefined ? this.options.defaultTopic : topic,
+            module,
+            traceId,
+            nodeId,
+            extra,
+            context,
+        };
+    }
+
+    private formatLevelTag(entry: LogEntry): string {
+        const emoji = this.options.formatEmoji ? `${this.levelEmojis[entry.level]} ` : "";
+        if (entry.level === LogLevel.CRITICAL) {
+            return `[${emoji}*** ${entry.level} ***]`;
+        }
+        return `[${emoji}${entry.level}]`;
+    }
+
+    private formatLog(entry: LogEntry): string {
+        const parts: string[] = [];
+
+        if (this.options.formatTimestamp) {
+            parts.push(`[${new Date(entry.timestamp).toISOString()}]`);
+        }
+
+        parts.push(this.formatLevelTag(entry));
+        parts.push(
+            `traceId=${entry.traceId} nodeId=${entry.nodeId ?? "--"} module=${entry.module} topic=${entry.topic ?? "--"}`
+        );
+
+        if (this.options.formatPrefix) {
+            parts.push(`prefix=${this.options.formatPrefix}`);
+        }
+
+        const message =
+            entry.level === LogLevel.CRITICAL ? `>>> ${entry.message} <<<` : entry.message;
+        parts.push(`| ${message}`);
+
+        if (entry.extra) {
+            parts.push(`| extra=${entry.extra}`);
+        }
+
+        const contextText = formatContextValue(entry.context);
+        if (contextText) {
+            parts.push(`| context=${contextText}`);
+        }
+
+        return parts.join(" ");
+    }
+
+    private emitLog(entry: LogEntry, formatted: string): void {
+        switch (entry.level) {
+            case LogLevel.WARN:
+                console.warn(formatted);
+                break;
+            case LogLevel.ERROR:
+            case LogLevel.CRITICAL:
+                console.error(formatted);
+                break;
+            default:
+                console.log(formatted);
+        }
+    }
+
+    private log(
+        level: LogLevel,
+        message: LogParams["message"],
+        logContext: LogContext,
+        restParams?: LogRestParams
+    ) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+
+        validateLogContext(logContext);
+
+        const { topic, extra, context } = restParams ?? {};
+        const { module, traceId, nodeId } = logContext;
+        const entry = this.createLogEntry({ level, message, topic, extra, context, module, traceId, nodeId });
+
+        this.history.push(entry);
+        if (this.history.length > this.options.maxHistoryLength) {
+            this.history.shift();
+        }
+
+        const formatted = this.formatLog(entry);
+        this.emitLog(entry, formatted);
+        this.options.onLog?.(entry);
+    }
+
+    public generateTraceId(): string {
+        return generateUniqueId();
+    }
+
+    public debug(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
+        this.log(LogLevel.DEBUG, message, logContext, restParams);
+    }
+
+    public info(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
+        this.log(LogLevel.INFO, message, logContext, restParams);
+    }
+
+    public success(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
+        this.log(LogLevel.SUCCESS, message, logContext, restParams);
+    }
+
+    public warn(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
+        this.log(LogLevel.WARN, message, logContext, restParams);
+    }
+
+    public error(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
+        this.log(LogLevel.ERROR, message, logContext, restParams);
+    }
+
+    public critical(message: LogParams["message"], logContext: LogContext, restParams?: LogRestParams) {
+        this.log(LogLevel.CRITICAL, message, logContext, restParams);
+    }
+
+    public withContext(context: LogContext): { logger: LoggerWithContext; context: LogContext } {
+        const boundContext: LogContext = { ...context };
+
+        const logger: LoggerWithContext = {
+            debug: (message, restParams) => this.debug(message, boundContext, restParams),
+            info: (message, restParams) => this.info(message, boundContext, restParams),
+            success: (message, restParams) => this.success(message, boundContext, restParams),
+            warn: (message, restParams) => this.warn(message, boundContext, restParams),
+            error: (message, restParams) => this.error(message, boundContext, restParams),
+            critical: (message, restParams) => this.critical(message, boundContext, restParams),
+            resetContext: (fields) => {
+                Object.assign(boundContext, fields);
+            },
+        };
+
+        return { logger, context: boundContext };
+    }
+}
+
+export const logManager = LogManager.getInstance();
+export { LogManager, LogLevel };
+export { createApiLogger } from "./create-api-logger";
+export type { CreateApiLoggerOptions } from "./create-api-logger";
+export type { LogOptions, LogEntry, LogContext, LoggerWithContext, LogRestParams };

package/src/shared/utils/config-path.utils.ts

@@ -0,0 +1,104 @@
+import { access } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Directory containing a config file — anchor for paths declared **inside** that file.
+ */
+export function getConfigFileDir(configFilePath: string): string {
+    return dirname(configFilePath);
+}
+
+/**
+ * Resolve a path from a config file's directory.
+ *
+ * - Absolute `pathInConfig` → returned as-is
+ * - Relative `pathInConfig` → `resolve(dirname(configFilePath), pathInConfig)`
+ *
+ * **Not** relative to `process.cwd()`. See `.cursor/skills/config-file-relative-paths/SKILL.md`.
+ */
+export function resolvePathFromConfigFile(configFilePath: string, pathInConfig: string): string {
+    const trimmed = pathInConfig.trim();
+    if (isAbsolute(trimmed)) {
+        return trimmed;
+    }
+    return resolve(getConfigFileDir(configFilePath), trimmed);
+}
+
+/**
+ * Resolve a path from an explicit base directory (e.g. task package dir for `entry`).
+ * Same rules as {@link resolvePathFromConfigFile}, but base is already known.
+ */
+export function resolvePathFromBaseDir(baseDir: string, path: string): string {
+    const trimmed = path.trim();
+    if (isAbsolute(trimmed)) {
+        return trimmed;
+    }
+    return resolve(baseDir, trimmed);
+}
+
+/**
+ * Resolve a path from `cwd` — for **discovering** config files, not for fields inside them.
+ */
+export function resolvePathFromCwd(cwd: string, path: string): string {
+    const trimmed = path.trim();
+    if (isAbsolute(trimmed)) {
+        return trimmed;
+    }
+    return resolve(cwd, trimmed);
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+    try {
+        await access(path);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export interface ResolveFirstExistingPathOptions {
+    /** When set, only this path is tried (resolved from `cwd` if relative). */
+    explicitPath?: string;
+    /** Relative to `cwd`, tried in order when `explicitPath` is omitted. */
+    candidatePaths: string[];
+}
+
+/**
+ * Find the first existing file path: optional explicit path, else scan `candidatePaths` under `cwd`.
+ */
+export async function resolveFirstExistingPath(
+    cwd: string,
+    options: ResolveFirstExistingPathOptions
+): Promise<string | null> {
+    const { explicitPath, candidatePaths } = options;
+
+    if (explicitPath != null && explicitPath.trim() !== "") {
+        const resolved = resolvePathFromCwd(cwd, explicitPath);
+        return (await pathExists(resolved)) ? resolved : null;
+    }
+
+    for (const candidate of candidatePaths) {
+        const resolved = join(cwd, candidate);
+        if (await pathExists(resolved)) {
+            return resolved;
+        }
+    }
+
+    return null;
+}
+
+/** `file://` href for Node dynamic `import()` of a local module. */
+export function toFileImportHref(filePath: string): string {
+    const trimmed = filePath.trim();
+    if (trimmed.includes("://")) {
+        return trimmed;
+    }
+    return pathToFileURL(trimmed).href;
+}
+
+/** Native ESM import of a `.js` / `.mjs` config; supports `export default` or named export object. */
+export async function importJsConfigModule(configPath: string): Promise<unknown> {
+    const mod = await import(toFileImportHref(configPath));
+    return mod.default ?? mod;
+}