target-supabase-sdk 0.1.8 → 0.2.0

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 { LoggerWithScope } from "../shared/log";
+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: LoggerWithScope;
+    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", data: { cacheKey } });
+        return cached;
+    }
+
+    const { source, modulePath, exportName } = script.details;
+
+    try {
+        let moduleExports: unknown;
+        if (source != null && source.trim() !== "") {
+            logger.info("从 source 动态加载 Repo 脚本", { topic: "repo", data: { scriptId: script.id } });
+            moduleExports = await importFromSource(source, cacheKey);
+        } else if (modulePath != null && modulePath.trim() !== "") {
+            logger.info("从 modulePath 动态加载 Repo 脚本", {
+                topic: "repo",
+                data: { scriptId: script.id, modulePath },
+            });
+            moduleExports = await importFromFilePath(modulePath);
+        } else {
+            logger.warn("脚本缺少 source 或 modulePath", { topic: "repo", data: { scriptId: script.id } });
+            return null;
+        }
+
+        const context = normalizeRepoContextModule(moduleExports, taskTypeKey, exportName);
+        if (context == null) {
+            logger.warn("脚本模块未导出合法的 TaskRepoContext", {
+                topic: "repo",
+                data: { 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",
+            data: { scriptId: script.id, error: error instanceof Error ? error.message : error },
+        });
+        return null;
+    }
+}
+
+export async function loadRepoContextFromUrl({
+    logger,
+    url,
+    taskTypeKey,
+    exportName,
+}: {
+    logger: LoggerWithScope;
+    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", data: { cacheKey } });
+        return cached;
+    }
+
+    try {
+        logger.info("从 Repo URL 动态加载脚本", { topic: "repo", data: { url, href } });
+        const moduleExports = await import(href);
+        const context = normalizeRepoContextModule(moduleExports, taskTypeKey, exportName);
+        if (context == null) {
+            logger.warn("Repo URL 模块未导出合法的 TaskRepoContext", {
+                topic: "repo",
+                data: { 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",
+            data: { 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,36 @@
+import { logManager, type LoggerWithScope } from "./log-manager";
+import { normalizeScope, type LogScope, type LogScopePatch } from "./log-scope";
+
+/**
+ * Options for {@link createApiLogger}.
+ *
+ * - **Trace:** optional `traceId` / `traceParentId` (generated root when traceId omitted)
+ * - **Labels:** optional `labels` (e.g. `{ nodeId }`)
+ */
+export type CreateApiLoggerOptions = {
+    traceId?: string;
+    traceParentId?: string | null;
+    labels?: Record<string, string>;
+} & Partial<Omit<LogScope, "module" | "traceId" | "traceParentId" | "labels">>;
+
+/**
+ * Logger for one SDK API invocation.
+ *
+ * Binds `module` + normalized {@link LogScope}.
+ */
+export function createApiLogger(module: string, options?: CreateApiLoggerOptions): LoggerWithScope {
+    const { traceId, traceParentId, labels, ...rest } = options ?? {};
+    const scope = normalizeScope(
+        {
+            module,
+            traceId,
+            traceParentId: traceParentId ?? null,
+            labels,
+            ...rest,
+        },
+        { generateTraceId: true }
+    );
+    return logManager.withScope(scope).logger;
+}
+
+export type { LogScopePatch };

package/src/shared/log/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Log domain public API — curated re-exports only.
+ */
+
+// log-manager
+export { logManager, LogManager, LogLevel } from "./log-manager";
+export type { LogEntry, LogOptions, LoggerWithScope, LogRestParams } from "./log-manager";
+
+// create-api-logger
+export { createApiLogger } from "./create-api-logger";
+export type { CreateApiLoggerOptions } from "./create-api-logger";
+
+// log-scope
+export {
+    applyScopePatch,
+    createChildScope,
+    createRootScope,
+    formatScopeLabels,
+    normalizeScope,
+    resolveLogData,
+    withModule,
+} from "./log-scope";
+export type { LogScope, LogScopeInput, LogScopePatch, CreateRootScopeInput, CreateChildScopeInput } from "./log-scope";

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

@@ -0,0 +1,335 @@
+import { isDevEnvironment } from "../../core.utils";
+import { generateUniqueId } from "../utils/id.utils";
+import {
+    applyScopePatch,
+    formatScopeLabels,
+    resolveLogData,
+    type LogScope,
+    type LogScopePatch,
+} from "./log-scope";
+
+/**
+ * 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 extends LogScope {
+    timestamp: number;
+    level: LogLevel;
+    message: string;
+    topic: string | null;
+    extra?: string;
+    /** Per-line structured business payload. */
+    data?: unknown;
+}
+
+type LogRestParams = {
+    topic?: LogEntry["topic"];
+    extra?: LogEntry["extra"];
+    data?: unknown;
+};
+
+type LogParams = { message: LogEntry["message"] } & LogRestParams;
+
+interface LogEntryPayload extends LogScope {
+    message: LogEntry["message"];
+    topic?: LogEntry["topic"];
+    extra?: LogEntry["extra"];
+    data?: LogEntry["data"];
+    level: LogEntry["level"];
+}
+
+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 LoggerWithScope {
+    debug: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    info: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    success: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    warn: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    error: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    critical: (message: LogParams["message"], restParams?: LogRestParams) => void;
+    /** Merge partial fields into this logger's bound scope. */
+    resetScope: (fields: LogScopePatch) => void;
+    /** @deprecated use {@link LoggerWithScope.resetScope} */
+    resetContext: (fields: LogScopePatch) => void;
+}
+
+function mergeLogOptions(options?: Partial<LogOptions>): LogOptions {
+    return { ...DEFAULT_OPTIONS, ...options };
+}
+
+function formatDataValue(value: unknown): string {
+    if (value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return JSON.stringify(value);
+    } catch {
+        return String(value);
+    }
+}
+
+function validateLogScope(logScope: LogScope): void {
+    const missing: string[] = [];
+    if (!logScope.module?.trim()) {
+        missing.push("module");
+    }
+    if (!logScope.traceId?.trim()) {
+        missing.push("traceId");
+    }
+    if (logScope.traceParentId !== null && typeof logScope.traceParentId !== "string") {
+        missing.push("traceParentId");
+    }
+    if (missing.length > 0) {
+        console.warn(`[LogManager] LogScope missing or invalid: ${missing.join(", ")}`, logScope);
+    }
+}
+
+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(payload: LogEntryPayload): LogEntry {
+        const { level, message, topic, extra, data, module, traceId, traceParentId, labels } = payload;
+        return {
+            timestamp: Date.now(),
+            level,
+            message,
+            topic: topic === undefined ? this.options.defaultTopic : topic,
+            module,
+            traceId,
+            traceParentId,
+            labels,
+            extra,
+            data,
+        };
+    }
+
+    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} parent=${entry.traceParentId ?? "null"} labels=${formatScopeLabels(entry.labels)} 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 dataText = formatDataValue(entry.data);
+        if (dataText) {
+            parts.push(`| data=${dataText}`);
+        }
+
+        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"], logScope: LogScope, restParams?: LogRestParams) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+
+        validateLogScope(logScope);
+
+        const { topic, extra } = restParams ?? {};
+        const data = resolveLogData(restParams);
+        const entry = this.createLogEntry({
+            level,
+            message,
+            topic,
+            extra,
+            data,
+            ...logScope,
+        });
+
+        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"], logScope: LogScope, restParams?: LogRestParams) {
+        this.log(LogLevel.DEBUG, message, logScope, restParams);
+    }
+
+    public info(message: LogParams["message"], logScope: LogScope, restParams?: LogRestParams) {
+        this.log(LogLevel.INFO, message, logScope, restParams);
+    }
+
+    public success(message: LogParams["message"], logScope: LogScope, restParams?: LogRestParams) {
+        this.log(LogLevel.SUCCESS, message, logScope, restParams);
+    }
+
+    public warn(message: LogParams["message"], logScope: LogScope, restParams?: LogRestParams) {
+        this.log(LogLevel.WARN, message, logScope, restParams);
+    }
+
+    public error(message: LogParams["message"], logScope: LogScope, restParams?: LogRestParams) {
+        this.log(LogLevel.ERROR, message, logScope, restParams);
+    }
+
+    public critical(message: LogParams["message"], logScope: LogScope, restParams?: LogRestParams) {
+        this.log(LogLevel.CRITICAL, message, logScope, restParams);
+    }
+
+    public withScope(scope: LogScope): { logger: LoggerWithScope; scope: LogScope } {
+        const boundScope: LogScope = { ...scope, labels: scope.labels ? { ...scope.labels } : undefined };
+
+        const logger: LoggerWithScope = {
+            debug: (message, restParams) => this.debug(message, boundScope, restParams),
+            info: (message, restParams) => this.info(message, boundScope, restParams),
+            success: (message, restParams) => this.success(message, boundScope, restParams),
+            warn: (message, restParams) => this.warn(message, boundScope, restParams),
+            error: (message, restParams) => this.error(message, boundScope, restParams),
+            critical: (message, restParams) => this.critical(message, boundScope, restParams),
+            resetScope: (fields) => {
+                const next = applyScopePatch(boundScope, fields);
+                boundScope.module = next.module;
+                boundScope.traceId = next.traceId;
+                boundScope.traceParentId = next.traceParentId;
+                boundScope.labels = next.labels;
+            },
+            resetContext: (fields) => {
+                logger.resetScope(fields);
+            },
+        };
+
+        return { logger, scope: boundScope };
+    }
+
+}
+
+export const logManager = LogManager.getInstance();
+export { LogManager, LogLevel };
+export type { LogOptions, LogEntry, LoggerWithScope, LogRestParams };

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

@@ -0,0 +1,123 @@
+import { generateUniqueId } from "../utils/id.utils";
+
+/** Logger-bound scope: module + trace chain + optional labels. */
+export interface LogScope {
+    module: string;
+    traceId: string;
+    traceParentId: string | null;
+    labels?: Readonly<Record<string, string>>;
+}
+
+/** Partial update for {@link LogScope} / {@link applyScopePatch}. */
+export type LogScopePatch = Partial<Omit<LogScope, "labels">> & {
+    labels?: Record<string, string>;
+};
+
+export type LogScopeInput = LogScopePatch & Pick<LogScope, "module">;
+
+interface NormalizeScopeOptions {
+    /** When true and traceId is missing, generate a new id. */
+    generateTraceId?: boolean;
+}
+
+function mergeLabels(
+    base?: Readonly<Record<string, string>>,
+    patch?: Record<string, string>
+): Record<string, string> | undefined {
+    const merged: Record<string, string> = { ...base, ...patch };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+/** Coerce partial input into a {@link LogScope}. */
+export function normalizeScope(input: LogScopeInput, options?: NormalizeScopeOptions): LogScope {
+    const generateTraceId = options?.generateTraceId ?? false;
+    const traceId = input.traceId?.trim() || (generateTraceId ? generateUniqueId() : "");
+    if (!traceId) {
+        throw new Error("[LogScope] traceId is required (or enable generateTraceId)");
+    }
+
+    return {
+        module: input.module,
+        traceId,
+        traceParentId: input.traceParentId ?? null,
+        labels: mergeLabels(undefined, input.labels),
+    };
+}
+
+/** Input for {@link createRootScope}. */
+export type CreateRootScopeInput = {
+    module: string;
+    traceId?: string;
+    labels?: Record<string, string>;
+    traceParentId?: string | null;
+};
+
+/** Root scope: traceParentId defaults to null. */
+export function createRootScope(input: CreateRootScopeInput): LogScope {
+    return normalizeScope(
+        {
+            module: input.module,
+            traceId: input.traceId,
+            traceParentId: input.traceParentId ?? null,
+            labels: input.labels,
+        },
+        { generateTraceId: true }
+    );
+}
+
+/** Input for {@link createChildScope}. */
+export type CreateChildScopeInput = {
+    module: string;
+    parent: LogScope;
+    traceId?: string;
+    traceParentId?: string | null;
+    labels?: Record<string, string>;
+};
+
+/** Child scope: parent link defaults to parent.traceId; labels merge with parent. */
+export function createChildScope(input: CreateChildScopeInput): LogScope {
+    const { module, parent, traceId, traceParentId, labels } = input;
+    return normalizeScope(
+        {
+            module,
+            traceId,
+            traceParentId: traceParentId ?? parent.traceId,
+            labels: mergeLabels(parent.labels, labels),
+        },
+        { generateTraceId: true }
+    );
+}
+
+/** Same trace chain, different module (e.g. prepareTask vs executeTask). */
+export function withModule(scope: LogScope, module: string): LogScope {
+    return { ...scope, module };
+}
+
+/** Merge patch into scope (labels deep-merge). */
+export function applyScopePatch(scope: LogScope, patch: LogScopePatch): LogScope {
+    return normalizeScope({
+        module: patch.module ?? scope.module,
+        traceId: patch.traceId ?? scope.traceId,
+        traceParentId: patch.traceParentId !== undefined ? patch.traceParentId : scope.traceParentId,
+        labels: mergeLabels(scope.labels, patch.labels),
+    });
+}
+export function formatScopeLabels(labels?: Readonly<Record<string, string>>): string {
+    if (labels == null || Object.keys(labels).length === 0) {
+        return "--";
+    }
+    return Object.entries(labels)
+        .map(([key, value]) => `${key}:${value}`)
+        .join(",");
+}
+
+/** Prefer `data`; fall back to deprecated `context` on log rest params. */
+export function resolveLogData(rest?: { data?: unknown; context?: unknown }): unknown | undefined {
+    if (rest?.data !== undefined) {
+        return rest.data;
+    }
+    if (rest?.context !== undefined) {
+        return rest.context;
+    }
+    return undefined;
+}