target-supabase-sdk 0.1.9 → 0.2.0

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

@@ -1,4 +1,4 @@
-import { readdir } from "node:fs/promises";
+import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 
 import { RepoManager } from "../repo/repo-manager";
@@ -23,6 +23,11 @@ export interface BootstrapLocalTasksOptions {
     rootConfigPath?: string;
     /** Base directory for resolving root config (default `process.cwd()`) */
     cwd?: string;
+    /**
+     * When set with an unchanged config fingerprint, skip full scan if this key is already
+     * registered in {@link RepoManager}.
+     */
+    forTaskTypeKey?: string;
 }
 
 const EMPTY_RESULT: BootstrapLocalTasksResult = {
@@ -32,6 +37,14 @@ const EMPTY_RESULT: BootstrapLocalTasksResult = {
     errors: [],
 };
 
+type BootstrapCacheState = {
+    fingerprint: string | null;
+    lastResult: BootstrapLocalTasksResult | null;
+};
+
+let bootstrapCache: BootstrapCacheState = { fingerprint: null, lastResult: null };
+let bootstrapInFlight: Promise<BootstrapLocalTasksResult> | null = null;
+
 function parseRootConfig(raw: unknown, configPath: string): TaskRunnerRootConfig {
     if (raw == null || typeof raw !== "object") {
         throw new Error(`Root config must export an object: ${configPath}`);
@@ -78,24 +91,46 @@ function finalizeStatus(result: Omit<BootstrapLocalTasksResult, "status">): Boot
     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 = {}
+async function computeConfigFingerprint(rootConfigPath: string, tasksRoot: string): Promise<string> {
+    const rootStat = await stat(rootConfigPath);
+    const tasksRootStat = await stat(tasksRoot);
+    const entries = await readdir(tasksRoot, { withFileTypes: true });
+    const configMtims: number[] = [];
+
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const configPath = join(tasksRoot, entry.name, TASK_LOCAL_PACKAGE_CONFIG_FILENAME);
+        if (await pathExists(configPath)) {
+            const configStat = await stat(configPath);
+            configMtims.push(configStat.mtimeMs);
+        }
+    }
+
+    configMtims.sort((a, b) => a - b);
+    return `${rootConfigPath}:${rootStat.mtimeMs}:${tasksRoot}:${tasksRootStat.mtimeMs}:${configMtims.join(",")}`;
+}
+
+function canUseCachedBootstrap(
+    fingerprint: string,
+    forTaskTypeKey: string | undefined
+): BootstrapLocalTasksResult | null {
+    if (bootstrapCache.fingerprint !== fingerprint || bootstrapCache.lastResult == null) {
+        return null;
+    }
+
+    if (forTaskTypeKey != null && forTaskTypeKey !== "") {
+        if (!RepoManager.hasLocalRepo(forTaskTypeKey)) {
+            return null;
+        }
+    }
+
+    return { ...bootstrapCache.lastResult, cached: true };
+}
+
+async function runBootstrapScan(
+    options: BootstrapLocalTasksOptions
 ): Promise<BootstrapLocalTasksResult> {
     const cwd = options.cwd ?? process.cwd();
 
@@ -107,10 +142,12 @@ export async function bootstrapLocalTasks(
         ],
     });
     if (rootConfigPath == null) {
-        return {
+        const result: BootstrapLocalTasksResult = {
             ...EMPTY_RESULT,
             message: `No root config (tried ${TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH}, ${TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH})`,
         };
+        bootstrapCache = { fingerprint: null, lastResult: result };
+        return result;
     }
 
     const result: Omit<BootstrapLocalTasksResult, "status"> = {
@@ -125,11 +162,19 @@ export async function bootstrapLocalTasks(
 
         const tasksRoot = resolvePathFromConfigFile(rootConfigPath, taskDir);
         if (!(await pathExists(tasksRoot))) {
-            return {
+            const failed: BootstrapLocalTasksResult = {
                 status: "failed",
                 message: `taskDir does not exist: ${tasksRoot}`,
                 ...result,
             };
+            bootstrapCache = { fingerprint: null, lastResult: failed };
+            return failed;
+        }
+
+        const fingerprint = await computeConfigFingerprint(rootConfigPath, tasksRoot);
+        const cached = canUseCachedBootstrap(fingerprint, options.forTaskTypeKey);
+        if (cached != null) {
+            return cached;
         }
 
         const entries = await readdir(tasksRoot, { withFileTypes: true });
@@ -171,7 +216,7 @@ export async function bootstrapLocalTasks(
         }
 
         const status = finalizeStatus(result);
-        return {
+        const finalResult: BootstrapLocalTasksResult = {
             status,
             message:
                 status === "empty"
@@ -179,13 +224,55 @@ export async function bootstrapLocalTasks(
                     : undefined,
             ...result,
         };
+        bootstrapCache = { fingerprint, lastResult: finalResult };
+        return finalResult;
     } catch (error) {
-        return {
+        const failed: BootstrapLocalTasksResult = {
             status: "failed",
             message: error instanceof Error ? error.message : String(error),
             ...result,
         };
+        bootstrapCache = { fingerprint: null, lastResult: failed };
+        return failed;
+    }
+}
+
+/**
+ * Discover local task packages from config files and register them with {@link RepoManager}.
+ *
+ * **Never throws** for missing root config — returns `{ status: "not_configured" }`.
+ *
+ * Re-scans are skipped when the config fingerprint is unchanged (root config + taskDir mtimes).
+ * Concurrent calls share a single in-flight scan (single-flight).
+ *
+ * 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> {
+    if (bootstrapInFlight != null) {
+        return bootstrapInFlight;
     }
+
+    bootstrapInFlight = runBootstrapScan(options).finally(() => {
+        bootstrapInFlight = null;
+    });
+    return bootstrapInFlight;
+}
+
+/** Clear fingerprint cache (tests / hot-reload tooling). */
+export function clearBootstrapLocalTasksCache(): void {
+    bootstrapCache = { fingerprint: null, lastResult: null };
+    bootstrapInFlight = null;
 }
 
 export function getRegisteredLocalTaskTypeKeys(): string[] {

package/src/task/task-manager.ts

@@ -1,9 +1,8 @@
-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 { LoggerWithScope } from "../shared/log";
 import { ResultCode, Task } from "./task.interface";
-import { TaskFn, TaskRepoContext, TaskRunResult, ExecutableTaskFn } from "./task-repo-context";
+import { TaskFn, TaskRunResult, ExecutableTaskFn } from "./task-repo-context";
 
 export type {
     TaskFn,
@@ -28,15 +27,21 @@ export {
 import {
     bootstrapLocalTasks,
     BootstrapLocalTasksOptions,
+    clearBootstrapLocalTasksCache,
     getRegisteredLocalTaskTypeKeys,
 } from "./local-task-registry";
 import type { BootstrapLocalTasksResult } from "./task-repo-context";
+import { TaskRepoValidation, type TaskRepoValidationFailureReason } from "./task-repo-validation";
 
-export type PrepareTaskFailureReason =
-    | "MISSING_PARAMS"
-    | "REPO_LOAD_FAILED"
-    | "PARAMS_VALIDATION_FAILED"
-    | "TASK_TYPE_KEY_MISMATCH";
+/** @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;
@@ -49,12 +54,18 @@ export interface PrepareTaskResponse {
 }
 
 export interface PrepareTaskParams {
-    logger: LoggerWithContext;
+    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: LoggerWithContext;
+    logger: LoggerWithScope;
     local?: BootstrapLocalTasksOptions;
     /** When `true` (default), union local keys with remote `Repo.value` from Supabase. */
     includeRemote?: boolean;
@@ -64,32 +75,33 @@ export interface RegisterTasksResult {
     availableTaskList: string[];
     local: BootstrapLocalTasksResult;
     remote: { values: string[] };
+    includeRemote: boolean;
 }
 
-function logLocalBootstrap(logger: LoggerWithContext, bootstrap: BootstrapLocalTasksResult): void {
+function logLocalBootstrap(logger: LoggerWithScope, bootstrap: BootstrapLocalTasksResult): void {
     switch (bootstrap.status) {
         case "not_configured":
             logger.info("未找到本地任務配置，跳過本地註冊", {
                 topic: "task",
-                context: { message: bootstrap.message },
+                data: { message: bootstrap.message },
             });
             break;
         case "failed":
             logger.warn("本地任務註冊失敗", {
                 topic: "task",
-                context: { message: bootstrap.message, errors: bootstrap.errors },
+                data: { message: bootstrap.message, errors: bootstrap.errors },
             });
             break;
         case "empty":
             logger.info("本地任務掃描完成，無已註冊任務", {
                 topic: "task",
-                context: { message: bootstrap.message, skipped: bootstrap.skipped },
+                data: { message: bootstrap.message, skipped: bootstrap.skipped },
             });
             break;
         case "loaded":
             logger.info("本地任務註冊完成", {
                 topic: "task",
-                context: {
+                data: {
                     registered: bootstrap.registered,
                     skipped: bootstrap.skipped,
                     errors: bootstrap.errors,
@@ -122,7 +134,7 @@ async function registerTasks({
     if (includeRemote) {
         logger.info("查詢遠程 Repo 列表", {
             topic: "task",
-            context: { usage: TASK_REPO_USAGE },
+            data: { usage: TASK_REPO_USAGE },
         });
         const { data, error: remoteError } = await getScanRemoteRepoValues({ usage: TASK_REPO_USAGE });
         if (remoteError) {
@@ -131,7 +143,7 @@ async function registerTasks({
         remoteValues = data ?? [];
         logger.info("遠程 Repo 查詢完成", {
             topic: "task",
-            context: { count: remoteValues.length, values: remoteValues },
+            data: { count: remoteValues.length, values: remoteValues },
         });
     }
 
@@ -142,7 +154,7 @@ async function registerTasks({
 
     logger.success("任務註冊完成", {
         topic: "task",
-        context: {
+        data: {
             availableTaskList,
             localRegistered: local.registered,
             remoteValues,
@@ -153,10 +165,11 @@ async function registerTasks({
         availableTaskList,
         local,
         remote: { values: remoteValues },
+        includeRemote,
     };
 }
 
-/** 将 taskFn 与 params 闭包绑定，供 NodeManager 无参调用 `await taskFn()` */
+/** 将 taskFn 与 params 闭包绑定，供 TaskNode 无参调用 `await taskFn()` */
 function bindTaskFn(taskFn: TaskFn, taskParams: unknown): ExecutableTaskFn {
     const run = async () => taskFn(taskParams);
     return Object.assign(run, {
@@ -165,36 +178,23 @@ function bindTaskFn(taskFn: TaskFn, taskParams: unknown): ExecutableTaskFn {
     });
 }
 
-/** 调用 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，返回閉包後的無參執行函數
+ * 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 }: PrepareTaskParams): Promise<PrepareTaskResponse> => {
+const prepareTask = async ({
+    logger,
+    task,
+    includeRemote = true,
+    bootstrapLocalOptions,
+}: PrepareTaskParams): Promise<PrepareTaskResponse> => {
     const fail = (params: {
         reason: PrepareTaskFailureReason;
         code: ResultCode;
@@ -203,7 +203,7 @@ const prepareTask = async ({ logger, task }: PrepareTaskParams): Promise<Prepare
     }): PrepareTaskResponse => {
         logger.warn(params.message, {
             topic: "task",
-            context: {
+            data: {
                 taskId: task.id,
                 taskTypeKey: task.value,
                 reason: params.reason,
@@ -223,72 +223,60 @@ const prepareTask = async ({ logger, task }: PrepareTaskParams): Promise<Prepare
     const { id: taskId, name: taskName, value: taskTypeKey, details } = task;
     logger.info(`開始準備任務 ${taskName}-${taskTypeKey}`, {
         topic: "task",
-        context: { taskId, taskName, taskTypeKey },
+        data: { taskId, taskName, taskTypeKey },
     });
 
     const { params: taskParams } = details;
-    if (taskParams == null) {
-        return fail({
-            reason: "MISSING_PARAMS",
-            code: ResultCode.PARAMS_NOT_VALID,
-            message: "任務缺少 params",
-            step: "params",
+
+    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,
+            },
         });
     }
 
-    logger.debug("任務詳情校驗通過，開始解析 Repo 上下文", {
-        topic: "task",
-        context: { taskTypeKey, step: "repo_load" },
-    });
-
-    const { context: repoContext, error: repoError } = await RepoManager.getRepoContext<TaskRepoContext>({
+    const validation = await TaskRepoValidation.validate({
         logger,
         taskTypeKey,
+        params: taskParams,
+        includeRemote,
     });
-
-    if (repoContext == null) {
+    if (!validation.isValid) {
         return fail({
-            reason: "REPO_LOAD_FAILED",
-            code: ResultCode.REPO_NOT_VALID,
-            message: repoError ?? "無法加載 Repo 上下文",
-            step: "repo_load",
+            reason: validation.reason,
+            code: validation.code,
+            message: validation.message,
+            step: validation.step,
         });
     }
 
+    const { repoContext } = validation;
+
     logger.info("Repo 上下文加載成功", {
         topic: "task",
-        context: {
+        data: {
             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: {
+        data: {
             taskId,
             taskTypeKey,
             displayName: boundTaskFn.displayName,
@@ -307,6 +295,7 @@ const TaskManager = {
     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

@@ -86,6 +86,8 @@ export interface BootstrapLocalTasksResult {
     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 */