target-supabase-sdk 0.1.8 → 0.2.0

package/src/node/trigger-node.ts

@@ -0,0 +1,180 @@
+import { logManager, type LoggerWithScope } from "../shared/log";
+import { scopeForNodeLoop } from "./node-log-scope";
+import { postTask } from "../task/task-post.api";
+import { TaskStatus } from "../task/task.interface";
+import { patchTriggerFired, scanEnabledTriggers } from "../trigger/trigger.api";
+import type { Trigger, TriggerPostTaskAction } from "../trigger/trigger.interface";
+import { buildFireKey, isTriggerDue } from "../trigger/trigger.utils";
+import { NodeLoopContext } from "./node.interface";
+import { BaseNodeRuntime } from "./node-runtime.base";
+
+/**
+ * Dedicated trigger scheduler node.
+ * Main loop: commands → heartbeat → evaluate due triggers → postTask.
+ *
+ * Phase 1: run a **single** TriggerNode process per deployment to avoid duplicate fires.
+ */
+class TriggerNode extends BaseNodeRuntime {
+    constructor() {
+        super("triggerNode");
+    }
+
+    protected async onBeforeRegisterNode(logger: LoggerWithScope): Promise<void> {
+        logger.info("Trigger 節點啟動，跳過任務註冊", { topic: "trigger" });
+    }
+
+    protected async runLoopSteps(ctx: NodeLoopContext, heartbeatOk: boolean): Promise<void> {
+        const loopScope = scopeForNodeLoop({
+            module: `${this.runtimeModule}-loop-iteration`,
+            traceId: ctx.loopTraceId,
+            nodeId: ctx.nodeId,
+        });
+        if (!heartbeatOk) {
+            const { logger } = logManager.withScope(loopScope);
+            logger.warn("心跳失敗，本輪跳過 Trigger 評估", { topic: "trigger" });
+            return;
+        }
+        await this.evaluateTriggers(ctx);
+    }
+
+    async evaluateTriggers(ctx: NodeLoopContext): Promise<void> {
+        const { loopTraceId, nodeId } = ctx;
+        const loopScope = scopeForNodeLoop({ module: "evaluateTriggers", traceId: loopTraceId, nodeId });
+        const { logger } = logManager.withScope(loopScope);
+
+        logger.debug("開始評估 Trigger", { topic: "trigger" });
+
+        const { data: triggerList = [], error } = await scanEnabledTriggers({ traceId: loopTraceId });
+        if (error) {
+            logger.warn("掃描 Trigger 失敗", {
+                topic: "trigger",
+                data: { error: error.message },
+            });
+            return;
+        }
+        if (triggerList.length === 0) {
+            logger.info("無 ENABLED Trigger", { topic: "trigger" });
+            return;
+        }
+
+        const now = new Date();
+        let dueCount = 0;
+        let firedCount = 0;
+
+        for (const trigger of triggerList) {
+            if (!isTriggerDue(trigger, now)) {
+                continue;
+            }
+            dueCount++;
+            const fired = await this.fireTrigger(ctx, trigger, now);
+            if (fired) {
+                firedCount++;
+            }
+        }
+
+        logger.info("Trigger 評估完成", {
+            topic: "trigger",
+            data: {
+                scanned: triggerList.length,
+                due: dueCount,
+                fired: firedCount,
+            },
+        });
+    }
+
+    private async fireTrigger(ctx: NodeLoopContext, trigger: Trigger, now: Date): Promise<boolean> {
+        const { loopTraceId, nodeId } = ctx;
+        const { logger } = logManager.withScope(
+            scopeForNodeLoop({ module: "fireTrigger", traceId: loopTraceId, nodeId })
+        );
+
+        const fireKey = buildFireKey(trigger, now);
+        const action = trigger.details.action;
+
+        if (action.kind !== "post_task") {
+            logger.warn("不支援的 Trigger action", {
+                topic: "trigger",
+                data: { triggerId: trigger.id, kind: action.kind },
+            });
+            return false;
+        }
+
+        logger.info("Trigger 到期，準備 postTask", {
+            topic: "trigger",
+            data: {
+                triggerId: trigger.id,
+                triggerKey: trigger.value,
+                fireKey,
+                taskTypeKey: action.taskTypeKey,
+            },
+        });
+
+        const taskExtra = `trigger:${trigger.id}:${fireKey}`;
+        const { data: task, error: postError } = await postTask(
+            buildPostTaskPayload(trigger, action, taskExtra, loopTraceId)
+        );
+
+        if (postError) {
+            logger.error("Trigger postTask 失敗", {
+                topic: "trigger",
+                data: {
+                    triggerId: trigger.id,
+                    fireKey,
+                    error: postError.message,
+                },
+            });
+            return false;
+        }
+
+        const { error: patchError } = await patchTriggerFired({
+            triggerId: trigger.id,
+            fireKey,
+            expectedLastFireKey: trigger.details.lastFireKey ?? null,
+            traceId: loopTraceId,
+        });
+
+        if (patchError) {
+            logger.warn("Trigger 已 postTask 但更新 lastFireKey 失敗", {
+                topic: "trigger",
+                data: {
+                    triggerId: trigger.id,
+                    taskId: task?.id,
+                    fireKey,
+                    error: patchError.message,
+                },
+            });
+            return false;
+        }
+
+        logger.success("Trigger 觸發成功", {
+            topic: "trigger",
+            data: {
+                triggerId: trigger.id,
+                triggerKey: trigger.value,
+                fireKey,
+                taskId: task?.id,
+                taskTraceId: task?.details.traceId,
+            },
+        });
+        return true;
+    }
+}
+
+function buildPostTaskPayload(
+    trigger: Trigger,
+    action: TriggerPostTaskAction,
+    extra: string,
+    loopTraceId: string
+) {
+    return {
+        name: action.taskName ?? trigger.name,
+        value: action.taskTypeKey,
+        params: action.taskParams,
+        taskStatus: action.taskStatus ?? TaskStatus.TODO,
+        tagList: trigger.tagList ?? [],
+        extra,
+        traceParentId: loopTraceId,
+    };
+}
+
+export { TriggerNode };

package/src/node.ts

@@ -0,0 +1,62 @@
+/**
+ * Node.js runtime entry — browser API plus local FS / worker orchestration.
+ *
+ * import { TaskManager, RepoManager, TaskNode } from "target-supabase-sdk/node";
+ */
+
+export * from "./browser";
+
+export { TaskManager } from "./task/task-manager";
+export type {
+	PrepareTaskFailureReason,
+	PrepareTaskParams,
+	PrepareTaskResponse,
+	RegisterTasksOptions,
+	RegisterTasksResult,
+	TaskFn,
+	TaskRepoContext,
+	TaskRunResult,
+	ExecutableTaskFn,
+	TaskRepoScriptDetails,
+	TaskRepoScriptRecord,
+	TaskRunnerRootConfig,
+	TaskLocalPackageConfig,
+	BootstrapLocalTasksResult,
+	BootstrapLocalTasksStatus,
+} from "./task/task-manager";
+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/task-manager";
+
+export {
+	postTask,
+	postTaskSchema,
+} from "./task/task-post.api";
+export type { PostTaskPayload } from "./task/task-post.api";
+
+export {
+	TaskRepoValidation,
+	validateTaskRepoAndParams,
+} from "./task/task-repo-validation";
+export type {
+	TaskRepoValidationFailureReason,
+	ValidateTaskRepoAndParamsInput,
+	ValidateTaskRepoAndParamsResult,
+} from "./task/task-repo-validation";
+
+export { RepoManager } from "./repo/repo-manager";
+
+export { TaskNode } from "./node/task-node";
+export { TriggerNode } from "./node/trigger-node";
+export { BaseNodeRuntime } from "./node/node-runtime.base";
+
+export * from "./command/command.interface";
+export * from "./command/command.api";
+
+export * from "./trigger/trigger.interface";
+export * from "./trigger/trigger.api";

package/src/parcel/parcel-manager.ts

@@ -206,4 +206,4 @@ const ParcelManager = {
   reassembly,
 };
 
-export default ParcelManager;
+export { ParcelManager };

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

@@ -0,0 +1,111 @@
+import {
+    TASK_REPO_SCRIPT_CATEGORY,
+    type TaskRepoContext,
+    type TaskRepoScriptDetails,
+    type TaskRepoScriptRecord,
+} from "../task/task-repo-context";
+
+export { TASK_REPO_SCRIPT_CATEGORY };
+
+export interface LoadedRepoContext {
+    context: TaskRepoContext;
+    /** Cache key segment — typically repo hash or script hash */
+    contentHash: string;
+}
+
+export function isTaskRepoContext(value: unknown): value is TaskRepoContext {
+    if (value == null || typeof value !== "object") {
+        return false;
+    }
+    const record = value as TaskRepoContext;
+    return typeof record.taskParamsValidator === "function" && typeof record.taskFn === "function";
+}
+
+/**
+ * Normalize a dynamically imported module into {@link TaskRepoContext}.
+ * Supported shapes:
+ * - `export default { taskParamsValidator, taskFn }`
+ * - `export { taskParamsValidator, taskFn }`
+ * - `export default taskFn` (validator becomes `() => true`)
+ */
+export function normalizeRepoContextModule(
+    moduleExports: unknown,
+    taskTypeKey: string,
+    exportName?: string
+): TaskRepoContext | null {
+    if (moduleExports == null) {
+        return null;
+    }
+
+    const record = moduleExports as Record<string, unknown>;
+    const namedExport =
+        exportName != null && exportName !== "" ? record[exportName] : undefined;
+    const defaultExport = record.default;
+    const candidate = namedExport ?? defaultExport ?? moduleExports;
+
+    let taskParamsValidator: unknown;
+    let taskFn: unknown;
+
+    if (typeof candidate === "function") {
+        taskFn = candidate;
+        taskParamsValidator = record.taskParamsValidator;
+    } else if (typeof candidate === "object" && candidate != null) {
+        const ctx = candidate as Record<string, unknown>;
+        taskParamsValidator = ctx.taskParamsValidator;
+        taskFn = ctx.taskFn;
+    }
+
+    taskParamsValidator ??= record.taskParamsValidator;
+    taskFn ??= record.taskFn;
+
+    if (typeof taskFn !== "function") {
+        return null;
+    }
+
+    if (typeof taskParamsValidator !== "function") {
+        taskParamsValidator = () => true;
+    }
+
+    const fn = taskFn as TaskRepoContext["taskFn"];
+    if (fn.displayName == null || fn.displayName === "") {
+        fn.displayName = taskTypeKey;
+    }
+    if (fn.taskTypeKey == null || fn.taskTypeKey === "") {
+        fn.taskTypeKey = taskTypeKey;
+    }
+
+    return {
+        taskParamsValidator: taskParamsValidator as TaskRepoContext["taskParamsValidator"],
+        taskFn: fn,
+    };
+}
+
+export function pickEntryScript(scripts: TaskRepoScriptRecord[]): TaskRepoScriptRecord | null {
+    if (scripts.length === 0) {
+        return null;
+    }
+    const entry = scripts.find((script) => script.details.isEntry === true);
+    return entry ?? scripts[0];
+}
+
+export function getScriptLoadKey(script: TaskRepoScriptRecord): string {
+    const { source, modulePath, hash } = script.details;
+    if (hash != null && hash !== "") {
+        return hash;
+    }
+    if (source != null && source !== "") {
+        return `source:${source.length}:${source.slice(0, 64)}`;
+    }
+    if (modulePath != null && modulePath !== "") {
+        return `path:${modulePath}`;
+    }
+    return script.id;
+}
+
+export function assertScriptLoadable(
+    details: TaskRepoScriptDetails
+): details is TaskRepoScriptDetails & ({ source: string } | { modulePath: string }) {
+    const hasSource = details.source != null && details.source.trim() !== "";
+    const hasModulePath = details.modulePath != null && details.modulePath.trim() !== "";
+    return hasSource || hasModulePath;
+}

package/src/repo/repo-manager.ts

@@ -0,0 +1,245 @@
+import { getPossibleTarget } from "../core.api";
+import { SupabaseInitializer } from "../supabase";
+import { LoggerWithScope } from "../shared/log";
+import type { TaskRepoContext, TaskRepoScriptRecord } from "../task/task-repo-context";
+import { TASK_REPO_SCRIPT_CATEGORY } from "../task/task-repo-context";
+import {
+    assertScriptLoadable,
+    isTaskRepoContext,
+    pickEntryScript,
+} from "./repo-context.utils";
+import { CategoryRepo, Repo } from "./repo.interface";
+import {
+    clearRepoScriptModuleCache,
+    loadRepoContextFromScript,
+    loadRepoContextFromUrl,
+} from "./repo.script-loader";
+
+const supabase = SupabaseInitializer.getInstance();
+
+type LocalRepoEntry =
+    | { kind: "context"; context: TaskRepoContext }
+    | { kind: "modulePath"; modulePath: string; exportName?: string };
+
+const localRepoRegistry = new Map<string, LocalRepoEntry>();
+const remoteContextCache = new Map<string, TaskRepoContext>();
+
+export type RepoContextFailureReason =
+    | "LOCAL_REPO_LOAD_FAILED"
+    | "LOCAL_REPO_NOT_FOUND"
+    | "REMOTE_REPO_NOT_FOUND"
+    | "REMOTE_REPO_LOAD_FAILED";
+
+export type RepoContextResolvedVia = "local" | "remote";
+
+export interface GetRepoContextParams {
+    logger: LoggerWithScope;
+    /** Task type key (`task.value`) — matches {@link Repo.value} for remote lookup; local registry key */
+    taskTypeKey: string;
+    /**
+     * When false, skip Supabase fetch if the task type is not in the local registry.
+     * Default `true`.
+     */
+    includeRemote?: boolean;
+}
+
+export interface GetRepoContextResult<T extends TaskRepoContext = TaskRepoContext> {
+    context: T | null;
+    /** Present when `context` is null — import / DB / format failure at repo layer */
+    error?: string;
+    failureReason?: RepoContextFailureReason;
+    resolvedVia?: RepoContextResolvedVia;
+}
+
+function buildRemoteCacheKey(taskTypeKey: string, contentHash: string): string {
+    return `${taskTypeKey}@${contentHash}`;
+}
+
+async function fetchRemoteRepo(taskTypeKey: string): Promise<Repo | null> {
+    const { data } = await getPossibleTarget({
+        filterList: [
+            { field: "category", operator: "eq", value: CategoryRepo.REPO },
+            { field: "value", operator: "eq", value: taskTypeKey },
+        ],
+    });
+    return (data as Repo | null) ?? null;
+}
+
+async function fetchRemoteScripts(taskTypeKey: string): Promise<TaskRepoScriptRecord[]> {
+    const { data, error } = await supabase.client
+        .from("target")
+        .select("id, value, details")
+        .eq("category", TASK_REPO_SCRIPT_CATEGORY)
+        .eq("value", taskTypeKey);
+
+    if (error) {
+        throw error;
+    }
+
+    return (data ?? []) as TaskRepoScriptRecord[];
+}
+
+async function loadLocalEntry(
+    logger: LoggerWithScope,
+    entry: LocalRepoEntry,
+    taskTypeKey: string
+): Promise<TaskRepoContext | null> {
+    if (entry.kind === "context") {
+        return entry.context;
+    }
+
+    const loaded = await loadRepoContextFromScript({
+        logger,
+        script: {
+            id: `local:${taskTypeKey}`,
+            value: taskTypeKey,
+            details: {
+                manifestVersion: 0,
+                modulePath: entry.modulePath,
+                exportName: entry.exportName,
+                isEntry: true,
+            },
+        },
+        taskTypeKey,
+    });
+    return loaded?.context ?? null;
+}
+
+async function loadRemoteRepoContext(
+    logger: LoggerWithScope,
+    taskTypeKey: string
+): Promise<GetRepoContextResult> {
+    logger.info("從 Supabase 加載 Repo", { topic: "repo", data: { taskTypeKey } });
+
+    const remoteRepo = await fetchRemoteRepo(taskTypeKey);
+    if (remoteRepo == null) {
+        const error = `Supabase 未找到 Repo (value=${taskTypeKey})`;
+        logger.warn(error, { topic: "repo", data: { taskTypeKey } });
+        return { context: null, error, failureReason: "REMOTE_REPO_NOT_FOUND" };
+    }
+
+    const repoUrl = remoteRepo.details?.url?.trim() ?? "";
+    const repoHash = remoteRepo.details?.hash?.trim() ?? repoUrl;
+    const cacheKey = buildRemoteCacheKey(taskTypeKey, repoHash);
+    const cached = remoteContextCache.get(cacheKey);
+    if (cached != null) {
+        logger.info("命中遠程 Repo 上下文緩存", { topic: "repo", data: { cacheKey } });
+        return { context: cached, resolvedVia: "remote" };
+    }
+
+    const scripts = await fetchRemoteScripts(taskTypeKey);
+    const entryScript = pickEntryScript(scripts);
+
+    let loaded =
+        entryScript != null && assertScriptLoadable(entryScript.details)
+            ? await loadRepoContextFromScript({ logger, script: entryScript, taskTypeKey })
+            : null;
+
+    if (loaded == null && repoUrl !== "") {
+        logger.info("未找到 script 行，嘗試從 Repo.details.url 加載", {
+            topic: "repo",
+            data: { taskTypeKey, url: repoUrl },
+        });
+        loaded = await loadRepoContextFromUrl({ logger, url: repoUrl, taskTypeKey });
+    }
+
+    if (loaded == null) {
+        const error = `無法從 Repo 加載 TaskRepoContext (hasUrl=${repoUrl !== ""}, scriptCount=${scripts.length})`;
+        logger.warn(error, {
+            topic: "repo",
+            data: { taskTypeKey, hasUrl: repoUrl !== "", scriptCount: scripts.length },
+        });
+        return { context: null, error, failureReason: "REMOTE_REPO_LOAD_FAILED" };
+    }
+
+    remoteContextCache.set(cacheKey, loaded.context);
+    return { context: loaded.context, resolvedVia: "remote" };
+}
+
+const getRepoContext = async <RepoContext extends TaskRepoContext>({
+    logger,
+    taskTypeKey,
+    includeRemote = true,
+}: GetRepoContextParams): Promise<GetRepoContextResult<RepoContext>> => {
+    const localEntry = localRepoRegistry.get(taskTypeKey);
+    if (localEntry != null) {
+        logger.info("使用本地註冊的 Repo", { topic: "repo", data: { taskTypeKey } });
+        const context = await loadLocalEntry(logger, localEntry, taskTypeKey);
+        if (context != null && isTaskRepoContext(context)) {
+            return { context: context as RepoContext, resolvedVia: "local" };
+        }
+        const error = "本地 Repo 模組加載失敗或未導出有效的 TaskRepoContext";
+        logger.warn(error, { topic: "repo", data: { taskTypeKey } });
+        return { context: null, error, failureReason: "LOCAL_REPO_LOAD_FAILED" };
+    }
+
+    if (!includeRemote) {
+        const error = `本地未註冊 Repo (value=${taskTypeKey})`;
+        logger.warn(error, { topic: "repo", data: { taskTypeKey, includeRemote: false } });
+        return { context: null, error, failureReason: "LOCAL_REPO_NOT_FOUND" };
+    }
+
+    try {
+        const result = await loadRemoteRepoContext(logger, taskTypeKey);
+        if (result.context != null && isTaskRepoContext(result.context)) {
+            return { context: result.context as RepoContext, resolvedVia: "remote" };
+        }
+        return {
+            context: null,
+            error: result.error ?? "遠程 Repo 上下文無效",
+            failureReason: result.failureReason ?? "REMOTE_REPO_LOAD_FAILED",
+        };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error("從 Supabase 加載 Repo 失敗", {
+            topic: "repo",
+            data: { taskTypeKey, error: message },
+        });
+        return { context: null, error: message, failureReason: "REMOTE_REPO_LOAD_FAILED" };
+    }
+};
+
+/** Register an in-process TaskRepoContext (highest priority — no Supabase fetch). */
+function registerLocalRepoContext(taskTypeKey: string, context: TaskRepoContext): void {
+    if (!isTaskRepoContext(context)) {
+        throw new Error("[RepoManager] Invalid TaskRepoContext");
+    }
+    localRepoRegistry.set(taskTypeKey, { kind: "context", context });
+}
+
+/** Register a local ESM module path; loaded via dynamic import when the task runs. */
+function registerLocalModule(taskTypeKey: string, modulePath: string, exportName?: string): void {
+    if (modulePath.trim() === "") {
+        throw new Error("[RepoManager] modulePath must not be empty");
+    }
+    localRepoRegistry.set(taskTypeKey, { kind: "modulePath", modulePath, exportName });
+}
+
+function unregisterLocalRepo(taskTypeKey: string): void {
+    localRepoRegistry.delete(taskTypeKey);
+}
+
+function hasLocalRepo(taskTypeKey: string): boolean {
+    return localRepoRegistry.has(taskTypeKey);
+}
+
+function getRegisteredLocalTaskTypeKeys(): string[] {
+    return [...localRepoRegistry.keys()];
+}
+
+function clearRemoteContextCache(): void {
+    remoteContextCache.clear();
+}
+
+const RepoManager = {
+    getRepoContext,
+    registerLocalRepoContext,
+    registerLocalModule,
+    unregisterLocalRepo,
+    hasLocalRepo,
+    getRegisteredLocalTaskTypeKeys,
+    clearRemoteContextCache,
+    clearRepoScriptModuleCache,
+};
+
+export { RepoManager };

package/src/repo/repo.api.ts

@@ -0,0 +1,50 @@
+import { scanTargetList, validateWithSchema } from "../core.api";
+import { generateResponse, SupabaseResponse } from "../core.interface";
+import { z } from "zod";
+import { CategoryRepo, Repo } from "./repo.interface";
+
+const REPO_USAGE_FIELD = "details->>usage" as const;
+
+export const getScanRemoteRepoValuesSchema = z.object({
+    usage: z.string().trim().min(1),
+});
+
+export type GetScanRemoteRepoValuesPayload = z.infer<typeof getScanRemoteRepoValuesSchema>;
+
+/**
+ * Scan `Repo.value` keys for `category=repo` with matching `details.usage`.
+ * Returns `{ data: string[] }` on success; validation and DB failures use `{ error }` (never throws).
+ */
+export const getScanRemoteRepoValues = async (
+    payload: GetScanRemoteRepoValuesPayload
+): Promise<SupabaseResponse<string[]>> => {
+    try {
+        return await getScanRemoteRepoValuesValidated(payload);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message) as SupabaseResponse<string[]>;
+    }
+};
+
+const getScanRemoteRepoValuesValidated = validateWithSchema(
+    getScanRemoteRepoValuesSchema,
+    "getScanRemoteRepoValuesSchema"
+)(async ({ usage }): Promise<SupabaseResponse<string[]>> => {
+    try {
+        const { data } = await scanTargetList<Repo>({
+            category: CategoryRepo.REPO,
+            selectFields: "value",
+            orderBy: { field: "value", ascending: true },
+            filterList: [{ field: REPO_USAGE_FIELD, operator: "eq", value: usage }],
+        });
+
+        const values = (data ?? [])
+            .map((row) => row.value?.trim())
+            .filter((value): value is string => value != null && value !== "");
+
+        return generateResponse.success([...new Set(values)]);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message) as SupabaseResponse<string[]>;
+    }
+});

package/src/repo/repo.interface.ts

@@ -3,13 +3,15 @@ import { Target } from "../core.interface";
 export enum CategoryRepo {
     /** Project */
     REPO = "repo",
-    SCRIPT = "script",
 }
 
+/** `Repo.details.usage` for task worker remote discovery ({@link registerTasks}). */
+export const TASK_REPO_USAGE = "task";
+
 export interface Repo extends Target {
-    /** Key */
+    /** Human readable name */
     name: string;
-    /** Url */
+    /** Unique key, consumers use this to determine which repo to use */
     value: string;
     details: RepoDetails;
     category: CategoryRepo;
@@ -17,7 +19,13 @@ export interface Repo extends Target {
 
 export interface RepoDetails {
     manifestVersion: number;
-    context?: unknown;
+    /**
+     * Business usage partition for discovery and load (caller-defined string, e.g. `"task"`).
+     * Used by {@link getScanRemoteRepoValues} to narrow scan scope; validity is the caller's responsibility.
+     */
+    usage: string;
+    /** Repo entry module URL or filesystem path — used to dynamic-import TaskRepoContext. */
+    url: string;
     hash: string;
-};
+}