target-supabase-sdk 0.1.8 → 0.2.0

package/src/shared/utils/config-path.utils.ts

@@ -0,0 +1,104 @@
+import { access } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Directory containing a config file — anchor for paths declared **inside** that file.
+ */
+export function getConfigFileDir(configFilePath: string): string {
+    return dirname(configFilePath);
+}
+
+/**
+ * Resolve a path from a config file's directory.
+ *
+ * - Absolute `pathInConfig` → returned as-is
+ * - Relative `pathInConfig` → `resolve(dirname(configFilePath), pathInConfig)`
+ *
+ * **Not** relative to `process.cwd()`. See `.cursor/skills/config-file-relative-paths/SKILL.md`.
+ */
+export function resolvePathFromConfigFile(configFilePath: string, pathInConfig: string): string {
+    const trimmed = pathInConfig.trim();
+    if (isAbsolute(trimmed)) {
+        return trimmed;
+    }
+    return resolve(getConfigFileDir(configFilePath), trimmed);
+}
+
+/**
+ * Resolve a path from an explicit base directory (e.g. task package dir for `entry`).
+ * Same rules as {@link resolvePathFromConfigFile}, but base is already known.
+ */
+export function resolvePathFromBaseDir(baseDir: string, path: string): string {
+    const trimmed = path.trim();
+    if (isAbsolute(trimmed)) {
+        return trimmed;
+    }
+    return resolve(baseDir, trimmed);
+}
+
+/**
+ * Resolve a path from `cwd` — for **discovering** config files, not for fields inside them.
+ */
+export function resolvePathFromCwd(cwd: string, path: string): string {
+    const trimmed = path.trim();
+    if (isAbsolute(trimmed)) {
+        return trimmed;
+    }
+    return resolve(cwd, trimmed);
+}
+
+export async function pathExists(path: string): Promise<boolean> {
+    try {
+        await access(path);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export interface ResolveFirstExistingPathOptions {
+    /** When set, only this path is tried (resolved from `cwd` if relative). */
+    explicitPath?: string;
+    /** Relative to `cwd`, tried in order when `explicitPath` is omitted. */
+    candidatePaths: string[];
+}
+
+/**
+ * Find the first existing file path: optional explicit path, else scan `candidatePaths` under `cwd`.
+ */
+export async function resolveFirstExistingPath(
+    cwd: string,
+    options: ResolveFirstExistingPathOptions
+): Promise<string | null> {
+    const { explicitPath, candidatePaths } = options;
+
+    if (explicitPath != null && explicitPath.trim() !== "") {
+        const resolved = resolvePathFromCwd(cwd, explicitPath);
+        return (await pathExists(resolved)) ? resolved : null;
+    }
+
+    for (const candidate of candidatePaths) {
+        const resolved = join(cwd, candidate);
+        if (await pathExists(resolved)) {
+            return resolved;
+        }
+    }
+
+    return null;
+}
+
+/** `file://` href for Node dynamic `import()` of a local module. */
+export function toFileImportHref(filePath: string): string {
+    const trimmed = filePath.trim();
+    if (trimmed.includes("://")) {
+        return trimmed;
+    }
+    return pathToFileURL(trimmed).href;
+}
+
+/** Native ESM import of a `.js` / `.mjs` config; supports `export default` or named export object. */
+export async function importJsConfigModule(configPath: string): Promise<unknown> {
+    const mod = await import(toFileImportHref(configPath));
+    return mod.default ?? mod;
+}

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/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Task domain public API — curated re-exports only.
+ * Internal modules (local-task-registry, task-repo-context, task.utils) stay private.
+ */
+
+// task.interface
+export {
+	CategoryTask,
+	ResultCode,
+	TaskStatus,
+	TaskStatusAction,
+} from "./task.interface";
+export type { Task, TaskDetails, TaskFlow } from "./task.interface";
+
+// task.api
+export {
+	patchChangeTaskStatus,
+	patchChangeTaskStatusSchema,
+	patchClaimTask,
+	patchClaimTaskSchema,
+	patchTaskProgress,
+	patchTaskProgressSchema,
+} from "./task.api";
+export type {
+	PatchChangeTaskStatusPayload,
+	PatchClaimTaskPayload,
+	PatchTaskProgressPayload,
+} from "./task.api";
+export { postTask, postTaskSchema } from "./task-post.api";
+export type { PostTaskPayload } from "./task-post.api";
+
+// task-manager
+export { TaskManager } from "./task-manager";
+export type {
+	PrepareTaskFailureReason,
+	PrepareTaskParams,
+	PrepareTaskResponse,
+	RegisterTasksOptions,
+	RegisterTasksResult,
+} from "./task-manager";
+
+// task-repo-validation
+export { TaskRepoValidation } from "./task-repo-validation";
+export type {
+	TaskRepoValidationFailureReason,
+	ValidateTaskRepoAndParamsInput,
+	ValidateTaskRepoAndParamsResult,
+} from "./task-repo-validation";

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

@@ -0,0 +1,282 @@
+import { readdir, stat } 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;
+    /**
+     * 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 = {
+    status: "not_configured",
+    registered: [],
+    skipped: [],
+    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}`);
+    }
+    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";
+}
+
+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,
+        ],
+    });
+    if (rootConfigPath == null) {
+        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"> = {
+        registered: [],
+        skipped: [],
+        errors: [],
+    };
+
+    try {
+        const rootRaw = await importJsConfigModule(rootConfigPath);
+        const { taskDir } = parseRootConfig(rootRaw, rootConfigPath);
+
+        const tasksRoot = resolvePathFromConfigFile(rootConfigPath, taskDir);
+        if (!(await pathExists(tasksRoot))) {
+            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 });
+        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);
+        const finalResult: BootstrapLocalTasksResult = {
+            status,
+            message:
+                status === "empty"
+                    ? `Root config loaded but no tasks registered under ${tasksRoot}`
+                    : undefined,
+            ...result,
+        };
+        bootstrapCache = { fingerprint, lastResult: finalResult };
+        return finalResult;
+    } catch (error) {
+        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();
+}
+
+export { TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH };