target-supabase-sdk 0.1.8 → 0.1.9

package/src/shared/utils/error.utils.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalize unknown catch / rejection values to {@link Error}.
+ *
+ * `catch` and Promise rejections are typed `unknown` because `throw` can be
+ * anything (string, number, plain object). Call sites that need `.message`,
+ * re-throw, or `instanceof Error` checks should normalize first.
+ */
+export function toError(value: unknown): Error {
+    return value instanceof Error ? value : new Error(String(value));
+}
+
+/** Error message safe for log `context` fields (JSON-serializable). */
+export function getErrorMessage(value: unknown): string {
+    return toError(value).message;
+}

package/src/shared/utils/id.utils.ts

@@ -0,0 +1,4 @@
+/** RFC 4122 v4 UUID for trace / correlation ids. Requires Node 18+ (`engines` in package.json). */
+export function generateUniqueId(): string {
+    return globalThis.crypto.randomUUID();
+}

package/src/supabase.ts

@@ -91,7 +91,7 @@ export class SupabaseInitializer {
     const authAnonKey = supabaseNeedAuthAnonKey;
 
     if (!mainUrl || !mainAnonKey) {
-      throw new Error("Missing required Supabase environment variables: VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY");
+      throw new Error("Missing required Supabase environment variables: SUPABASE_URL, SUPABASE_ANON_KEY");
     }
 
     return {

package/src/task/local-task-registry.ts

@@ -0,0 +1,195 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import { RepoManager } from "../repo/repo-manager";
+import {
+    importJsConfigModule,
+    pathExists,
+    resolveFirstExistingPath,
+    resolvePathFromBaseDir,
+    resolvePathFromConfigFile,
+} from "../shared/utils/config-path.utils";
+import {
+    BootstrapLocalTasksResult,
+    TASK_LOCAL_PACKAGE_CONFIG_FILENAME,
+    TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH,
+    TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH,
+    TaskLocalPackageConfig,
+    TaskRunnerRootConfig,
+} from "./task-repo-context";
+
+export interface BootstrapLocalTasksOptions {
+    /** Absolute or cwd-relative path to root config; if omitted, tries default paths under `cwd` */
+    rootConfigPath?: string;
+    /** Base directory for resolving root config (default `process.cwd()`) */
+    cwd?: string;
+}
+
+const EMPTY_RESULT: BootstrapLocalTasksResult = {
+    status: "not_configured",
+    registered: [],
+    skipped: [],
+    errors: [],
+};
+
+function parseRootConfig(raw: unknown, configPath: string): TaskRunnerRootConfig {
+    if (raw == null || typeof raw !== "object") {
+        throw new Error(`Root config must export an object: ${configPath}`);
+    }
+    const record = raw as Record<string, unknown>;
+    const taskDir = record.taskDir;
+    if (typeof taskDir !== "string" || taskDir.trim() === "") {
+        throw new Error(`Root config.taskDir must be a non-empty string: ${configPath}`);
+    }
+    return { taskDir: taskDir.trim() };
+}
+
+function parseTaskPackageConfig(raw: unknown, configPath: string): TaskLocalPackageConfig {
+    if (raw == null || typeof raw !== "object") {
+        throw new Error(`Task config must export an object: ${configPath}`);
+    }
+    const record = raw as Record<string, unknown>;
+    const taskTypeKey = record.taskTypeKey;
+    const entry = record.entry;
+
+    if (typeof taskTypeKey !== "string" || taskTypeKey.trim() === "") {
+        throw new Error(`taskTypeKey must be a non-empty string: ${configPath}`);
+    }
+    if (typeof entry !== "string" || entry.trim() === "") {
+        throw new Error(`entry must be a non-empty string: ${configPath}`);
+    }
+
+    return {
+        taskTypeKey: taskTypeKey.trim(),
+        entry: entry.trim(),
+        exportName: typeof record.exportName === "string" ? record.exportName : undefined,
+        displayName: typeof record.displayName === "string" ? record.displayName : undefined,
+        enabled: record.enabled === false ? false : true,
+    };
+}
+
+function finalizeStatus(result: Omit<BootstrapLocalTasksResult, "status">): BootstrapLocalTasksResult["status"] {
+    if (result.errors.length > 0 && result.registered.length === 0) {
+        return "failed";
+    }
+    if (result.registered.length === 0) {
+        return "empty";
+    }
+    return "loaded";
+}
+
+/**
+ * Discover local task packages from config files and register them with {@link RepoManager}.
+ *
+ * **Never throws** for missing root config — returns `{ status: "not_configured" }`.
+ *
+ * Host app layout (recommended):
+ * ```
+ * ./config/task.config.js       → { taskDir: "../tasks" }
+ * ./tasks/my-task/task.config.js
+ * ./tasks/my-task/index.mjs
+ * ```
+ *
+ * `taskDir` / `entry` paths are relative to **their config file's directory** (see config-file-relative-paths skill).
+ *
+ * Legacy fallback: `./task.config.js` at project root (`taskDir: "./tasks"`).
+ */
+export async function bootstrapLocalTasks(
+    options: BootstrapLocalTasksOptions = {}
+): Promise<BootstrapLocalTasksResult> {
+    const cwd = options.cwd ?? process.cwd();
+
+    const rootConfigPath = await resolveFirstExistingPath(cwd, {
+        explicitPath: options.rootConfigPath,
+        candidatePaths: [
+            TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH,
+            TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH,
+        ],
+    });
+    if (rootConfigPath == null) {
+        return {
+            ...EMPTY_RESULT,
+            message: `No root config (tried ${TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH}, ${TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH})`,
+        };
+    }
+
+    const result: Omit<BootstrapLocalTasksResult, "status"> = {
+        registered: [],
+        skipped: [],
+        errors: [],
+    };
+
+    try {
+        const rootRaw = await importJsConfigModule(rootConfigPath);
+        const { taskDir } = parseRootConfig(rootRaw, rootConfigPath);
+
+        const tasksRoot = resolvePathFromConfigFile(rootConfigPath, taskDir);
+        if (!(await pathExists(tasksRoot))) {
+            return {
+                status: "failed",
+                message: `taskDir does not exist: ${tasksRoot}`,
+                ...result,
+            };
+        }
+
+        const entries = await readdir(tasksRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+
+            const taskPackageDir = join(tasksRoot, entry.name);
+            const taskConfigPath = join(taskPackageDir, TASK_LOCAL_PACKAGE_CONFIG_FILENAME);
+
+            if (!(await pathExists(taskConfigPath))) {
+                result.skipped.push({ taskDir: taskPackageDir, reason: "missing task.config.js" });
+                continue;
+            }
+
+            try {
+                const taskRaw = await importJsConfigModule(taskConfigPath);
+                const taskConfig = parseTaskPackageConfig(taskRaw, taskConfigPath);
+
+                if (taskConfig.enabled === false) {
+                    result.skipped.push({ taskDir: taskPackageDir, reason: "disabled in task.config.js" });
+                    continue;
+                }
+
+                const entryPath = resolvePathFromBaseDir(taskPackageDir, taskConfig.entry);
+                if (!(await pathExists(entryPath))) {
+                    throw new Error(`entry module not found: ${entryPath}`);
+                }
+
+                RepoManager.registerLocalModule(taskConfig.taskTypeKey, entryPath, taskConfig.exportName);
+                result.registered.push(taskConfig.taskTypeKey);
+            } catch (error) {
+                result.errors.push({
+                    taskDir: taskPackageDir,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+
+        const status = finalizeStatus(result);
+        return {
+            status,
+            message:
+                status === "empty"
+                    ? `Root config loaded but no tasks registered under ${tasksRoot}`
+                    : undefined,
+            ...result,
+        };
+    } catch (error) {
+        return {
+            status: "failed",
+            message: error instanceof Error ? error.message : String(error),
+            ...result,
+        };
+    }
+}
+
+export function getRegisteredLocalTaskTypeKeys(): string[] {
+    return RepoManager.getRegisteredLocalTaskTypeKeys();
+}
+
+export { TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH };

package/src/task/task-manager.ts

@@ -0,0 +1,312 @@
+import { RepoManager } from "../repo/repo-manager";
+import { getScanRemoteRepoValues } from "../repo/repo.api";
+import { TASK_REPO_USAGE } from "../repo/repo.interface";
+import { LoggerWithContext } from "../shared/log/log-manager";
+import { ResultCode, Task } from "./task.interface";
+import { TaskFn, TaskRepoContext, TaskRunResult, ExecutableTaskFn } from "./task-repo-context";
+
+export type {
+    TaskFn,
+    TaskRepoContext,
+    TaskRunResult,
+    ExecutableTaskFn,
+    TaskRepoScriptDetails,
+    TaskRepoScriptRecord,
+    TaskRunnerRootConfig,
+    TaskLocalPackageConfig,
+    BootstrapLocalTasksResult,
+    BootstrapLocalTasksStatus,
+} from "./task-repo-context";
+export {
+    TASK_REPO_SCRIPT_CATEGORY,
+    TASK_RUNNER_CONFIG_DIR,
+    TASK_RUNNER_ROOT_CONFIG_FILENAME,
+    TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH,
+    TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH,
+    TASK_LOCAL_PACKAGE_CONFIG_FILENAME,
+} from "./task-repo-context";
+import {
+    bootstrapLocalTasks,
+    BootstrapLocalTasksOptions,
+    getRegisteredLocalTaskTypeKeys,
+} from "./local-task-registry";
+import type { BootstrapLocalTasksResult } from "./task-repo-context";
+
+export type PrepareTaskFailureReason =
+    | "MISSING_PARAMS"
+    | "REPO_LOAD_FAILED"
+    | "PARAMS_VALIDATION_FAILED"
+    | "TASK_TYPE_KEY_MISMATCH";
+
+export interface PrepareTaskResponse {
+    isSuccess: boolean;
+    taskFn: ExecutableTaskFn | null;
+    code?: ResultCode;
+    message?: string;
+    reason?: PrepareTaskFailureReason;
+    /** Pipeline step for log aggregation */
+    step?: string;
+}
+
+export interface PrepareTaskParams {
+    logger: LoggerWithContext;
+    task: Task;
+}
+
+export interface RegisterTasksOptions {
+    logger: LoggerWithContext;
+    local?: BootstrapLocalTasksOptions;
+    /** When `true` (default), union local keys with remote `Repo.value` from Supabase. */
+    includeRemote?: boolean;
+}
+
+export interface RegisterTasksResult {
+    availableTaskList: string[];
+    local: BootstrapLocalTasksResult;
+    remote: { values: string[] };
+}
+
+function logLocalBootstrap(logger: LoggerWithContext, bootstrap: BootstrapLocalTasksResult): void {
+    switch (bootstrap.status) {
+        case "not_configured":
+            logger.info("未找到本地任務配置，跳過本地註冊", {
+                topic: "task",
+                context: { message: bootstrap.message },
+            });
+            break;
+        case "failed":
+            logger.warn("本地任務註冊失敗", {
+                topic: "task",
+                context: { message: bootstrap.message, errors: bootstrap.errors },
+            });
+            break;
+        case "empty":
+            logger.info("本地任務掃描完成，無已註冊任務", {
+                topic: "task",
+                context: { message: bootstrap.message, skipped: bootstrap.skipped },
+            });
+            break;
+        case "loaded":
+            logger.info("本地任務註冊完成", {
+                topic: "task",
+                context: {
+                    registered: bootstrap.registered,
+                    skipped: bootstrap.skipped,
+                    errors: bootstrap.errors,
+                },
+            });
+            break;
+    }
+}
+
+/**
+ * Worker startup: discover local task packages + remote Repo rows, merge into `availableTaskList`.
+ *
+ * - Local: {@link bootstrapLocalTasks} → registers modules in {@link RepoManager}
+ * - Remote: {@link getScanRemoteRepoValues} with {@link TASK_REPO_USAGE}
+ * - Merge: union of both; execution still prefers local registry in {@link RepoManager.getRepoContext}
+ *
+ * @throws When merged list is empty (no task types to claim).
+ */
+async function registerTasks({
+    logger,
+    local: localOptions,
+    includeRemote = true,
+}: RegisterTasksOptions): Promise<RegisterTasksResult> {
+    logger.info("開始註冊任務（本地 + 遠程）", { topic: "task" });
+
+    const local = await bootstrapLocalTasks(localOptions ?? {});
+    logLocalBootstrap(logger, local);
+
+    let remoteValues: string[] = [];
+    if (includeRemote) {
+        logger.info("查詢遠程 Repo 列表", {
+            topic: "task",
+            context: { usage: TASK_REPO_USAGE },
+        });
+        const { data, error: remoteError } = await getScanRemoteRepoValues({ usage: TASK_REPO_USAGE });
+        if (remoteError) {
+            throw new Error(remoteError.message);
+        }
+        remoteValues = data ?? [];
+        logger.info("遠程 Repo 查詢完成", {
+            topic: "task",
+            context: { count: remoteValues.length, values: remoteValues },
+        });
+    }
+
+    const availableTaskList = [...new Set([...local.registered, ...remoteValues])];
+    if (availableTaskList.length === 0) {
+        throw new Error("[registerTasks] 任務註冊失敗：本地與遠程均無可用任務類型");
+    }
+
+    logger.success("任務註冊完成", {
+        topic: "task",
+        context: {
+            availableTaskList,
+            localRegistered: local.registered,
+            remoteValues,
+        },
+    });
+
+    return {
+        availableTaskList,
+        local,
+        remote: { values: remoteValues },
+    };
+}
+
+/** 将 taskFn 与 params 闭包绑定，供 NodeManager 无参调用 `await taskFn()` */
+function bindTaskFn(taskFn: TaskFn, taskParams: unknown): ExecutableTaskFn {
+    const run = async () => taskFn(taskParams);
+    return Object.assign(run, {
+        displayName: taskFn.displayName,
+        taskTypeKey: taskFn.taskTypeKey,
+    });
+}
+
+/** 调用 Repo 模块导出的 taskParamsValidator；抛错视为校验失败 */
+function validateTaskParams(
+    validator: TaskRepoContext["taskParamsValidator"],
+    taskParams: unknown,
+    logger: LoggerWithContext
+): boolean {
+    try {
+        return validator(taskParams) === true;
+    } catch (error) {
+        logger.warn("taskParamsValidator 拋出異常", {
+            topic: "task",
+            context: { error: error instanceof Error ? error.message : error },
+        });
+        return false;
+    }
+}
+
+/**
+ * 將 Supabase 認領到的 Task 解析為可執行的 `ExecutableTaskFn`。
+ *
+ * 流程：
+ * 1. 從 task.details 取出 `params`；`task.value` 作為 taskTypeKey（同 {@link Repo.value}）
+ * 2. {@link RepoManager.getRepoContext} — 本地註冊優先，否則按 task.value 拉取 Repo
+ * 3. 校驗 taskFn.taskTypeKey 與 task.value 一致
+ * 4. 用 Repo 導出的 taskParamsValidator 校驗 params
+ * 5. bindTaskFn，返回閉包後的無參執行函數
+ *
+ * 失敗時返回 `{ isSuccess: false, code, message, reason, step }`（不 throw）。
+ */
+const prepareTask = async ({ logger, task }: PrepareTaskParams): Promise<PrepareTaskResponse> => {
+    const fail = (params: {
+        reason: PrepareTaskFailureReason;
+        code: ResultCode;
+        message: string;
+        step: string;
+    }): PrepareTaskResponse => {
+        logger.warn(params.message, {
+            topic: "task",
+            context: {
+                taskId: task.id,
+                taskTypeKey: task.value,
+                reason: params.reason,
+                step: params.step,
+            },
+        });
+        return {
+            isSuccess: false,
+            taskFn: null,
+            code: params.code,
+            message: params.message,
+            reason: params.reason,
+            step: params.step,
+        };
+    };
+
+    const { id: taskId, name: taskName, value: taskTypeKey, details } = task;
+    logger.info(`開始準備任務 ${taskName}-${taskTypeKey}`, {
+        topic: "task",
+        context: { taskId, taskName, taskTypeKey },
+    });
+
+    const { params: taskParams } = details;
+    if (taskParams == null) {
+        return fail({
+            reason: "MISSING_PARAMS",
+            code: ResultCode.PARAMS_NOT_VALID,
+            message: "任務缺少 params",
+            step: "params",
+        });
+    }
+
+    logger.debug("任務詳情校驗通過，開始解析 Repo 上下文", {
+        topic: "task",
+        context: { taskTypeKey, step: "repo_load" },
+    });
+
+    const { context: repoContext, error: repoError } = await RepoManager.getRepoContext<TaskRepoContext>({
+        logger,
+        taskTypeKey,
+    });
+
+    if (repoContext == null) {
+        return fail({
+            reason: "REPO_LOAD_FAILED",
+            code: ResultCode.REPO_NOT_VALID,
+            message: repoError ?? "無法加載 Repo 上下文",
+            step: "repo_load",
+        });
+    }
+
+    logger.info("Repo 上下文加載成功", {
+        topic: "task",
+        context: {
+            taskTypeKey,
+            taskFnDisplayName: repoContext.taskFn.displayName,
+            step: "repo_load",
+        },
+    });
+
+    if (repoContext.taskFn.taskTypeKey !== taskTypeKey) {
+        return fail({
+            reason: "TASK_TYPE_KEY_MISMATCH",
+            code: ResultCode.REPO_NOT_VALID,
+            message: `taskFn.taskTypeKey (${repoContext.taskFn.taskTypeKey}) 與 task.value (${taskTypeKey}) 不一致`,
+            step: "task_type_key",
+        });
+    }
+
+    logger.debug("開始校驗任務參數", { topic: "task", context: { taskTypeKey, step: "params_validation" } });
+    if (!validateTaskParams(repoContext.taskParamsValidator, taskParams, logger)) {
+        return fail({
+            reason: "PARAMS_VALIDATION_FAILED",
+            code: ResultCode.PARAMS_NOT_VALID,
+            message: "任務參數校驗失敗",
+            step: "params_validation",
+        });
+    }
+
+    logger.debug("任務參數校驗通過", { topic: "task", context: { taskTypeKey, step: "params_validation" } });
+
+    const boundTaskFn = bindTaskFn(repoContext.taskFn, taskParams);
+    logger.success("任務準備完成", {
+        topic: "task",
+        context: {
+            taskId,
+            taskTypeKey,
+            displayName: boundTaskFn.displayName,
+            step: "bind",
+        },
+    });
+
+    return {
+        isSuccess: true,
+        taskFn: boundTaskFn,
+    };
+};
+
+const TaskManager = {
+    registerTasks,
+    prepareTask,
+    bootstrapLocalTasks,
+    getRegisteredLocalTaskTypeKeys,
+};
+
+export { TaskManager };

package/src/task/task-repo-context.ts

@@ -0,0 +1,103 @@
+export interface TaskRunResult {
+    isSuccess: boolean;
+    cost: number;
+    extra: unknown;
+}
+
+export interface TaskFn {
+    displayName: string;
+    taskTypeKey: string;
+    (taskParams: unknown): Promise<TaskRunResult>;
+}
+
+/** Params already bound — used by node executor after prepareTask */
+export type ExecutableTaskFn = (() => Promise<TaskRunResult>) & {
+    displayName: string;
+    taskTypeKey: string;
+};
+
+/** Repo script module must expose this shape (see repo-context.utils). */
+export interface TaskRepoContext {
+    taskParamsValidator: (taskParams: unknown) => boolean;
+    taskFn: TaskFn;
+}
+
+/** Supabase `target.category` for rows that store task script payloads */
+export const TASK_REPO_SCRIPT_CATEGORY = "script" as const;
+
+/**
+ * `target.details` for task script rows — not a separate Target subtype in repo.interface.
+ * Loaded dynamically to produce {@link TaskRepoContext}.
+ */
+export interface TaskRepoScriptDetails {
+    manifestVersion: number;
+    /** Inline ESM source — written to temp file then dynamically imported (Node) */
+    source?: string;
+    /** Absolute path to an ESM module on the worker machine */
+    modulePath?: string;
+    /** Named export to read TaskRepoContext from; default export if omitted */
+    exportName?: string;
+    /** Content hash for cache invalidation */
+    hash?: string;
+    /** Prefer this script as entry when multiple scripts exist for one repo */
+    isEntry?: boolean;
+}
+
+/** Minimal target row shape used by script loader (avoids a dedicated Script Target type). */
+export interface TaskRepoScriptRecord {
+    id: string;
+    value: string;
+    details: TaskRepoScriptDetails;
+}
+
+/** Host app root config at `config/task.config.js` — where to discover local task packages */
+export interface TaskRunnerRootConfig {
+    /** Directory containing one folder per task (relative to root config file), e.g. `"./tasks"` */
+    taskDir: string;
+}
+
+/** Per-task `task.config.js` inside `<taskDir>/<name>/` */
+export interface TaskLocalPackageConfig {
+    /** Must match `task.value` when claiming from Supabase */
+    taskTypeKey: string;
+    /** Entry module relative to this task folder, e.g. `"./index.mjs"` */
+    entry: string;
+    /** Named export on entry module; default export if omitted */
+    exportName?: string;
+    displayName?: string;
+    /** Skip registration when `false` (default `true`) */
+    enabled?: boolean;
+}
+
+export type BootstrapLocalTasksStatus =
+    /** Root config found and scan finished (individual tasks may still have errors) */
+    | "loaded"
+    /** Root config found but zero tasks registered */
+    | "empty"
+    /** No root config at default/explicit paths — not an error; use remote scripts or manual register */
+    | "not_configured"
+    /** Root config or taskDir invalid */
+    | "failed";
+
+export interface BootstrapLocalTasksResult {
+    status: BootstrapLocalTasksStatus;
+    /** Human-readable summary for logs */
+    message?: string;
+    registered: string[];
+    skipped: { taskDir: string; reason: string }[];
+    errors: { taskDir: string; error: string }[];
+}
+
+/** Host app config directory (relative to `cwd`) — recommended for library consumers */
+export const TASK_RUNNER_CONFIG_DIR = "config" as const;
+
+export const TASK_RUNNER_ROOT_CONFIG_FILENAME = "task.config.js" as const;
+
+/** Default root config path: `config/task.config.js` */
+export const TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH = `${TASK_RUNNER_CONFIG_DIR}/${TASK_RUNNER_ROOT_CONFIG_FILENAME}` as const;
+
+/** Legacy fallback at project root */
+export const TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH = TASK_RUNNER_ROOT_CONFIG_FILENAME;
+
+/** Per-task config filename inside each folder under `taskDir` */
+export const TASK_LOCAL_PACKAGE_CONFIG_FILENAME = "task.config.js" as const;