target-supabase-sdk 0.1.9 → 0.2.1

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";
@@ -10,12 +10,12 @@ import {
     resolvePathFromConfigFile,
 } from "../shared/utils/config-path.utils";
 import {
-    BootstrapLocalTasksResult,
+    type BootstrapLocalTasksResult,
     TASK_LOCAL_PACKAGE_CONFIG_FILENAME,
     TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH,
     TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH,
-    TaskLocalPackageConfig,
-    TaskRunnerRootConfig,
+    type TaskLocalPackageConfig,
+    type TaskRunnerRootConfig,
 } from "./task-repo-context";
 
 export interface BootstrapLocalTasksOptions {
@@ -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}`);
@@ -64,7 +77,7 @@ function parseTaskPackageConfig(raw: unknown, configPath: string): TaskLocalPack
         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,
+        enabled: record.enabled !== false,
     };
 }
 
@@ -78,39 +91,58 @@ 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 = {}
-): Promise<BootstrapLocalTasksResult> {
+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();
 
     const rootConfigPath = await resolveFirstExistingPath(cwd, {
         explicitPath: options.rootConfigPath,
-        candidatePaths: [
-            TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH,
-            TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH,
-        ],
+        candidatePaths: [TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH, TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH],
     });
     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 +157,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,23 +211,62 @@ export async function bootstrapLocalTasks(
         }
 
         const status = finalizeStatus(result);
-        return {
+        const finalResult: BootstrapLocalTasksResult = {
             status,
-            message:
-                status === "empty"
-                    ? `Root config loaded but no tasks registered under ${tasksRoot}`
-                    : undefined,
+            message: status === "empty" ? `Root config loaded but no tasks registered under ${tasksRoot}` : 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[] {
     return RepoManager.getRegisteredLocalTaskTypeKeys();
 }

package/src/task/task-manager.ts

@@ -1,60 +1,70 @@
-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";
+import type { LoggerWithScope } from "../shared/log";
+import type { ResultCode, Task } from "./task.interface";
+import type { ExecutableTaskFn, TaskFn } from "./task-repo-context";
 
 export type {
+    BootstrapLocalTasksResult,
+    BootstrapLocalTasksStatus,
+    ExecutableTaskFn,
     TaskFn,
+    TaskLocalPackageConfig,
     TaskRepoContext,
-    TaskRunResult,
-    ExecutableTaskFn,
     TaskRepoScriptDetails,
     TaskRepoScriptRecord,
     TaskRunnerRootConfig,
-    TaskLocalPackageConfig,
-    BootstrapLocalTasksResult,
-    BootstrapLocalTasksStatus,
+    TaskRunResult,
 } from "./task-repo-context";
 export {
+    TASK_LOCAL_PACKAGE_CONFIG_FILENAME,
     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,
+    TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH,
 } from "./task-repo-context";
+
 import {
+    type BootstrapLocalTasksOptions,
     bootstrapLocalTasks,
-    BootstrapLocalTasksOptions,
+    clearBootstrapLocalTasksCache,
     getRegisteredLocalTaskTypeKeys,
 } from "./local-task-registry";
+import { LOG_TOPIC_TASK } from "./task.constant";
 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";
+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;
+    reason?: TaskRepoValidationFailureReason;
     /** Pipeline step for log aggregation */
     step?: string;
 }
 
 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 +74,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 },
+                topic: LOG_TOPIC_TASK,
+                data: { message: bootstrap.message },
             });
             break;
         case "failed":
             logger.warn("本地任務註冊失敗", {
-                topic: "task",
-                context: { message: bootstrap.message, errors: bootstrap.errors },
+                topic: LOG_TOPIC_TASK,
+                data: { message: bootstrap.message, errors: bootstrap.errors },
             });
             break;
         case "empty":
             logger.info("本地任務掃描完成，無已註冊任務", {
-                topic: "task",
-                context: { message: bootstrap.message, skipped: bootstrap.skipped },
+                topic: LOG_TOPIC_TASK,
+                data: { message: bootstrap.message, skipped: bootstrap.skipped },
             });
             break;
         case "loaded":
             logger.info("本地任務註冊完成", {
-                topic: "task",
-                context: {
+                topic: LOG_TOPIC_TASK,
+                data: {
                     registered: bootstrap.registered,
                     skipped: bootstrap.skipped,
                     errors: bootstrap.errors,
@@ -113,36 +124,36 @@ async function registerTasks({
     local: localOptions,
     includeRemote = true,
 }: RegisterTasksOptions): Promise<RegisterTasksResult> {
-    logger.info("開始註冊任務（本地 + 遠程）", { topic: "task" });
+    logger.debug("開始註冊任務（本地 + 遠程）", { topic: LOG_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 },
+        logger.debug("查詢遠程 Repo 列表", {
+            topic: LOG_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",
-            context: { count: remoteValues.length, values: remoteValues },
+        logger.debug("遠程 Repo 查詢完成", {
+            topic: LOG_TOPIC_TASK,
+            data: { count: remoteValues.length, values: remoteValues },
         });
     }
 
     const availableTaskList = [...new Set([...local.registered, ...remoteValues])];
     if (availableTaskList.length === 0) {
-        throw new Error("[registerTasks] 任務註冊失敗：本地與遠程均無可用任務類型");
+        throw new Error("任務註冊失敗：本地與遠程均無可用任務類型");
     }
 
     logger.success("任務註冊完成", {
-        topic: "task",
-        context: {
+        topic: LOG_TOPIC_TASK,
+        data: {
             availableTaskList,
             localRegistered: local.registered,
             remoteValues,
@@ -153,10 +164,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,45 +177,32 @@ 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;
+        reason: TaskRepoValidationFailureReason;
         code: ResultCode;
         message: string;
         step: string;
     }): PrepareTaskResponse => {
         logger.warn(params.message, {
-            topic: "task",
-            context: {
+            topic: LOG_TOPIC_TASK,
+            data: {
                 taskId: task.id,
                 taskTypeKey: task.value,
                 reason: params.reason,
@@ -221,74 +220,62 @@ 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 },
+    logger.debug(`開始準備任務 ${taskName}-${taskTypeKey}`, {
+        topic: LOG_TOPIC_TASK,
+        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: LOG_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,
         });
     }
 
-    logger.info("Repo 上下文加載成功", {
-        topic: "task",
-        context: {
+    const { repoContext } = validation;
+
+    logger.debug("Repo 上下文加載成功", {
+        topic: LOG_TOPIC_TASK,
+        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: {
+    logger.debug("任務準備完成", {
+        topic: LOG_TOPIC_TASK,
+        data: {
             taskId,
             taskTypeKey,
             displayName: boundTaskFn.displayName,
@@ -307,6 +294,7 @@ const TaskManager = {
     prepareTask,
     bootstrapLocalTasks,
     getRegisteredLocalTaskTypeKeys,
+    clearBootstrapLocalTasksCache,
 };
 
 export { TaskManager };