target-supabase-sdk 0.1.8 → 0.2.0

package/src/task/task-manager.ts

@@ -0,0 +1,301 @@
+import { getScanRemoteRepoValues } from "../repo/repo.api";
+import { TASK_REPO_USAGE } from "../repo/repo.interface";
+import { LoggerWithScope } from "../shared/log";
+import { ResultCode, Task } from "./task.interface";
+import { TaskFn, 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,
+    clearBootstrapLocalTasksCache,
+    getRegisteredLocalTaskTypeKeys,
+} from "./local-task-registry";
+import type { BootstrapLocalTasksResult } from "./task-repo-context";
+import { TaskRepoValidation, type TaskRepoValidationFailureReason } from "./task-repo-validation";
+
+/** @deprecated use {@link TaskRepoValidationFailureReason} */
+export type PrepareTaskFailureReason = TaskRepoValidationFailureReason;
+
+export type {
+    TaskRepoValidationFailureReason,
+    ValidateTaskRepoAndParamsInput,
+    ValidateTaskRepoAndParamsResult,
+} from "./task-repo-validation";
+export { TaskRepoValidation } from "./task-repo-validation";
+
+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: LoggerWithScope;
+    task: Task;
+    /**
+     * When false, do not fetch Repo from Supabase during validation.
+     * Should match {@link RegisterTasksOptions.includeRemote} on the worker.
+     */
+    includeRemote?: boolean;
+    bootstrapLocalOptions?: BootstrapLocalTasksOptions;
+}
+
+export interface RegisterTasksOptions {
+    logger: LoggerWithScope;
+    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[] };
+    includeRemote: boolean;
+}
+
+function logLocalBootstrap(logger: LoggerWithScope, bootstrap: BootstrapLocalTasksResult): void {
+    switch (bootstrap.status) {
+        case "not_configured":
+            logger.info("未找到本地任務配置，跳過本地註冊", {
+                topic: "task",
+                data: { message: bootstrap.message },
+            });
+            break;
+        case "failed":
+            logger.warn("本地任務註冊失敗", {
+                topic: "task",
+                data: { message: bootstrap.message, errors: bootstrap.errors },
+            });
+            break;
+        case "empty":
+            logger.info("本地任務掃描完成，無已註冊任務", {
+                topic: "task",
+                data: { message: bootstrap.message, skipped: bootstrap.skipped },
+            });
+            break;
+        case "loaded":
+            logger.info("本地任務註冊完成", {
+                topic: "task",
+                data: {
+                    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",
+            data: { 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",
+            data: { count: remoteValues.length, values: remoteValues },
+        });
+    }
+
+    const availableTaskList = [...new Set([...local.registered, ...remoteValues])];
+    if (availableTaskList.length === 0) {
+        throw new Error("[registerTasks] 任務註冊失敗：本地與遠程均無可用任務類型");
+    }
+
+    logger.success("任務註冊完成", {
+        topic: "task",
+        data: {
+            availableTaskList,
+            localRegistered: local.registered,
+            remoteValues,
+        },
+    });
+
+    return {
+        availableTaskList,
+        local,
+        remote: { values: remoteValues },
+        includeRemote,
+    };
+}
+
+/** 将 taskFn 与 params 闭包绑定，供 TaskNode 无参调用 `await taskFn()` */
+function bindTaskFn(taskFn: TaskFn, taskParams: unknown): ExecutableTaskFn {
+    const run = async () => taskFn(taskParams);
+    return Object.assign(run, {
+        displayName: taskFn.displayName,
+        taskTypeKey: taskFn.taskTypeKey,
+    });
+}
+
+/**
+ * 將 Supabase 認領到的 Task 解析為可執行的 `ExecutableTaskFn`。
+ *
+ * 流程：
+ * 1. 從 task.details 取出 `params`；`task.value` 作為 taskTypeKey（同 {@link Repo.value}）
+ * 2. {@link TaskRepoValidation.validate} — 本地註冊優先；未命中時可選遠端（`includeRemote`）
+ *    Worker 在 registry 未命中時會補掃本地（`local_bootstrap_on_miss`）
+ * 3. bindTaskFn，返回閉包後的無參執行函數
+ *
+ * 失敗時返回 `{ isSuccess: false, code, message, reason, step }`（不 throw）。
+ */
+const prepareTask = async ({
+    logger,
+    task,
+    includeRemote = true,
+    bootstrapLocalOptions,
+}: PrepareTaskParams): Promise<PrepareTaskResponse> => {
+    const fail = (params: {
+        reason: PrepareTaskFailureReason;
+        code: ResultCode;
+        message: string;
+        step: string;
+    }): PrepareTaskResponse => {
+        logger.warn(params.message, {
+            topic: "task",
+            data: {
+                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",
+        data: { taskId, taskName, taskTypeKey },
+    });
+
+    const { params: taskParams } = details;
+
+    if (!getRegisteredLocalTaskTypeKeys().includes(taskTypeKey)) {
+        const bootstrap = await bootstrapLocalTasks({
+            ...bootstrapLocalOptions,
+            forTaskTypeKey: taskTypeKey,
+        });
+        logger.debug("本地 registry 未命中，補掃本地任務", {
+            topic: "task",
+            data: {
+                taskId,
+                taskTypeKey,
+                step: "local_bootstrap_on_miss",
+                status: bootstrap.status,
+                registered: bootstrap.registered,
+                cached: bootstrap.cached ?? false,
+                message: bootstrap.message,
+            },
+        });
+    }
+
+    const validation = await TaskRepoValidation.validate({
+        logger,
+        taskTypeKey,
+        params: taskParams,
+        includeRemote,
+    });
+    if (!validation.isValid) {
+        return fail({
+            reason: validation.reason,
+            code: validation.code,
+            message: validation.message,
+            step: validation.step,
+        });
+    }
+
+    const { repoContext } = validation;
+
+    logger.info("Repo 上下文加載成功", {
+        topic: "task",
+        data: {
+            taskTypeKey,
+            taskFnDisplayName: repoContext.taskFn.displayName,
+            step: "repo_load",
+        },
+    });
+
+    const boundTaskFn = bindTaskFn(repoContext.taskFn, taskParams);
+    logger.success("任務準備完成", {
+        topic: "task",
+        data: {
+            taskId,
+            taskTypeKey,
+            displayName: boundTaskFn.displayName,
+            step: "bind",
+        },
+    });
+
+    return {
+        isSuccess: true,
+        taskFn: boundTaskFn,
+    };
+};
+
+const TaskManager = {
+    registerTasks,
+    prepareTask,
+    bootstrapLocalTasks,
+    getRegisteredLocalTaskTypeKeys,
+    clearBootstrapLocalTasksCache,
+};
+
+export { TaskManager };

package/src/task/task-post.api.ts

@@ -0,0 +1,116 @@
+import { createTarget, validateWithSchema } from "../core.api";
+import { generateResponse, type SupabaseResponse } from "../core.interface";
+import { createApiLogger, logManager } from "../shared/log";
+import { z } from "zod";
+import { CategoryTask, ResultCode, Task, TaskStatus } from "./task.interface";
+import { TaskRepoValidation } from "./task-repo-validation";
+
+const traceIdSchema = z.string().trim().min(1).optional();
+const traceParentIdSchema = z.string().trim().min(1).nullable().optional();
+
+/** Initial status for a new task — OPEN (draft) or TODO (claimable by workers). */
+const postTaskInitialStatusSchema = z
+	.union([z.literal(TaskStatus.OPEN), z.literal(TaskStatus.TODO)])
+	.optional()
+	.default(TaskStatus.TODO);
+
+export const postTaskSchema = z.object({
+	name: z.string().trim().min(1),
+	/** Task type key — matches `task.value`, {@link patchClaimTask}, {@link Repo.value}, and local Repo registry. */
+	value: z.string().trim().min(1),
+	params: z.unknown(),
+	taskStatus: postTaskInitialStatusSchema,
+	tagList: z.array(z.string()).optional().default([]),
+	extra: z.string().optional(),
+	traceId: traceIdSchema,
+	traceParentId: traceParentIdSchema,
+});
+
+export type PostTaskPayload = z.infer<typeof postTaskSchema>;
+
+/**
+ * Create a task row (scheduler / admin). **Node entry only** — requires local Repo bootstrap.
+ *
+ * @see target-supabase-sdk/node
+ */
+export const postTask = validateWithSchema(
+	postTaskSchema,
+	"postTaskSchema",
+)(async ({
+	name,
+	value,
+	params,
+	taskStatus,
+	tagList,
+	extra,
+	traceId,
+	traceParentId,
+}) => {
+	const taskTraceId = traceId?.trim() || logManager.generateTraceId();
+	const logger = createApiLogger("postTask", {
+		traceId: taskTraceId,
+		traceParentId: traceParentId ?? null,
+	});
+
+	const validation = await TaskRepoValidation.validate({
+		logger,
+		taskTypeKey: value,
+		params,
+		bootstrapLocal: true,
+	});
+	if (!validation.isValid) {
+		logger.warn(validation.message, {
+			topic: "task",
+			data: {
+				taskTypeKey: value,
+				reason: validation.reason,
+				step: validation.step,
+			},
+		});
+		return generateResponse.error(
+			validation.message,
+			undefined,
+			String(validation.code),
+		) as SupabaseResponse<Task>;
+	}
+
+	const result = await createTarget<Task, PostTaskPayload>({
+		payload: {
+			name,
+			value,
+			params,
+			taskStatus,
+			tagList,
+			extra,
+			traceId: taskTraceId,
+			traceParentId,
+		},
+		createFn: () => ({
+			name,
+			value,
+			category: CategoryTask.TASK,
+			tagList,
+			extra,
+			details: {
+				manifestVersion: 0,
+				status: taskStatus,
+				params,
+				progress: 0,
+				nodeId: null,
+				traceId: taskTraceId,
+			},
+		}),
+	});
+
+	logger.info("任務已創建", {
+		topic: "task",
+		data: {
+			taskId: result.data?.id,
+			taskTypeKey: value,
+			status: taskStatus,
+			traceId: taskTraceId,
+		},
+	});
+
+	return result;
+});

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

@@ -0,0 +1,105 @@
+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 }[];
+    /** True when scan was skipped due to unchanged config fingerprint */
+    cached?: boolean;
+}
+
+/** 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;

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

@@ -0,0 +1,171 @@
+import { RepoManager, type RepoContextFailureReason } from "../repo/repo-manager";
+import { LoggerWithScope } from "../shared/log";
+import { bootstrapLocalTasks, type BootstrapLocalTasksOptions } from "./local-task-registry";
+import { ResultCode } from "./task.interface";
+import type { TaskRepoContext } from "./task-repo-context";
+
+export type TaskRepoValidationFailureReason =
+    | "MISSING_PARAMS"
+    | RepoContextFailureReason
+    | "PARAMS_VALIDATION_FAILED"
+    | "TASK_TYPE_KEY_MISMATCH";
+
+export type ValidateTaskRepoAndParamsInput = {
+    logger: LoggerWithScope;
+    taskTypeKey: string;
+    params: unknown;
+    /**
+     * When true, run {@link bootstrapLocalTasks} before resolve (CLI / Trigger / postTask).
+     * Worker paths should omit — {@link TaskManager.registerTasks} already bootstrapped.
+     */
+    bootstrapLocal?: boolean;
+    bootstrapLocalOptions?: BootstrapLocalTasksOptions;
+    /**
+     * When false, do not fetch Repo from Supabase if the task type is not locally registered.
+     * Default `true`. Align with {@link RegisterTasksOptions.includeRemote}.
+     */
+    includeRemote?: boolean;
+};
+
+export type ValidateTaskRepoAndParamsFailure = {
+    isValid: false;
+    code: ResultCode;
+    message: string;
+    reason: TaskRepoValidationFailureReason;
+    step: string;
+};
+
+export type ValidateTaskRepoAndParamsSuccess = {
+    isValid: true;
+    repoContext: TaskRepoContext;
+};
+
+export type ValidateTaskRepoAndParamsResult =
+    | ValidateTaskRepoAndParamsFailure
+    | ValidateTaskRepoAndParamsSuccess;
+
+function validateTaskParams(
+    validator: TaskRepoContext["taskParamsValidator"],
+    taskParams: unknown,
+    logger: LoggerWithScope
+): boolean {
+    try {
+        return validator(taskParams) === true;
+    } catch (error) {
+        logger.warn("taskParamsValidator 拋出異常", {
+            topic: "task",
+            data: { error: error instanceof Error ? error.message : error },
+        });
+        return false;
+    }
+}
+
+function invalid(params: {
+    reason: TaskRepoValidationFailureReason;
+    code: ResultCode;
+    message: string;
+    step: string;
+}): ValidateTaskRepoAndParamsFailure {
+    return { isValid: false, ...params };
+}
+
+/**
+ * Resolve task Repo context and validate `params` via `taskParamsValidator`.
+ *
+ * Repo resolution uses {@link RepoManager.getRepoContext}:
+ * local registry first; when no local entry and `includeRemote`, loads from Supabase.
+ */
+async function validateTaskRepoAndParams({
+    logger,
+    taskTypeKey,
+    params,
+    bootstrapLocal = false,
+    bootstrapLocalOptions,
+    includeRemote = true,
+}: ValidateTaskRepoAndParamsInput): Promise<ValidateTaskRepoAndParamsResult> {
+    if (params == null) {
+        return invalid({
+            reason: "MISSING_PARAMS",
+            code: ResultCode.PARAMS_NOT_VALID,
+            message: "任務缺少 params",
+            step: "params",
+        });
+    }
+
+    if (bootstrapLocal) {
+        const bootstrap = await bootstrapLocalTasks({
+            ...bootstrapLocalOptions,
+            forTaskTypeKey: taskTypeKey,
+        });
+        logger.debug("本地任務 bootstrap 完成", {
+            topic: "task",
+            data: {
+                taskTypeKey,
+                step: "local_bootstrap",
+                status: bootstrap.status,
+                registered: bootstrap.registered,
+                cached: bootstrap.cached ?? false,
+                message: bootstrap.message,
+            },
+        });
+    }
+
+    logger.debug("開始解析 Repo 上下文", {
+        topic: "task",
+        data: { taskTypeKey, step: "repo_load", includeRemote },
+    });
+
+    const {
+        context: repoContext,
+        error: repoError,
+        failureReason,
+        resolvedVia,
+    } = await RepoManager.getRepoContext<TaskRepoContext>({
+        logger,
+        taskTypeKey,
+        includeRemote,
+    });
+
+    if (repoContext == null) {
+        return invalid({
+            reason: failureReason ?? "REMOTE_REPO_LOAD_FAILED",
+            code: ResultCode.REPO_NOT_VALID,
+            message: repoError ?? "無法加載 Repo 上下文",
+            step: "repo_load",
+        });
+    }
+
+    logger.debug("Repo 上下文解析完成", {
+        topic: "task",
+        data: { taskTypeKey, step: "repo_load", resolvedVia },
+    });
+
+    if (repoContext.taskFn.taskTypeKey !== taskTypeKey) {
+        return invalid({
+            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", data: { taskTypeKey, step: "params_validation" } });
+    if (!validateTaskParams(repoContext.taskParamsValidator, params, logger)) {
+        return invalid({
+            reason: "PARAMS_VALIDATION_FAILED",
+            code: ResultCode.PARAMS_NOT_VALID,
+            message: "任務參數校驗失敗",
+            step: "params_validation",
+        });
+    }
+
+    logger.debug("任務參數校驗通過", { topic: "task", data: { taskTypeKey, step: "params_validation" } });
+
+    return { isValid: true, repoContext };
+}
+
+const TaskRepoValidation = {
+    validate: validateTaskRepoAndParams,
+};
+
+export { TaskRepoValidation, validateTaskRepoAndParams };