target-supabase-sdk 0.2.0 → 0.2.2

package/src/node/env/load-env.ts

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const DEFAULT_ENV_FILES = [".env.local", ".env"] as const;
+
+export interface LoadEnvFilesOptions {
+    /** Files to load in order (later files do not override existing env). */
+    files?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    /** Called after all files are merged (e.g. legacy alias normalization). */
+    afterLoad?: () => void;
+}
+
+function stripQuotes(value: string): string {
+    return value.replace(/^["']|["']$/g, "");
+}
+
+/** Parse one KEY=VALUE line; returns null if line should be skipped. */
+export function parseEnvLine(line: string): { key: string; value: string } | null {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) {
+        return null;
+    }
+
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) {
+        return null;
+    }
+
+    const key = trimmed.slice(0, eq).trim();
+    const raw = trimmed.slice(eq + 1).trim();
+    return { key, value: stripQuotes(raw) };
+}
+
+export function parseEnvFileContent(content: string, env: NodeJS.ProcessEnv): void {
+    for (const line of content.split("\n")) {
+        const parsed = parseEnvLine(line);
+        if (parsed == null) {
+            continue;
+        }
+        if (env[parsed.key] == null || env[parsed.key] === "") {
+            env[parsed.key] = parsed.value;
+        }
+    }
+}
+
+export function parseEnvFile(filePath: string, env: NodeJS.ProcessEnv): void {
+    if (!existsSync(filePath)) {
+        return;
+    }
+    parseEnvFileContent(readFileSync(filePath, "utf8"), env);
+}
+
+/**
+ * Load `.env.local` then `.env` into `process.env` (or `options.env`).
+ * Existing non-empty env values are not overwritten.
+ */
+export function loadEnvFiles(root: string, options?: LoadEnvFilesOptions): void {
+    const env = options?.env ?? process.env;
+    const files = options?.files ?? DEFAULT_ENV_FILES;
+
+    for (const name of files) {
+        parseEnvFile(resolve(root, name), env);
+    }
+
+    options?.afterLoad?.();
+}

package/src/node/env/project-root.ts

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Resolve project root from a module URL (typically `import.meta.url`).
+ * @param relativePath Path relative to the module file (default `".."` = parent directory).
+ */
+export function resolveProjectRootFromModule(importMetaUrl: string, relativePath = ".."): string {
+    return resolve(fileURLToPath(new URL(relativePath, importMetaUrl)));
+}
+
+/**
+ * Walk upward from `importMetaUrl` until a `package.json` with matching `name` is found.
+ * Use for esbuild bundles under `dist/` where a single `..` hop lands in `dist/`, not repo root.
+ */
+export function resolveProjectRootByPackageName(importMetaUrl: string, packageName: string): string {
+    let dir = dirname(fileURLToPath(importMetaUrl));
+    for (;;) {
+        const packageJsonPath = resolve(dir, "package.json");
+        if (existsSync(packageJsonPath)) {
+            const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { name?: string };
+            if (pkg.name === packageName) {
+                return dir;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    throw new Error(`Could not find package root for "${packageName}" from ${importMetaUrl}`);
+}

package/src/node/env/public-base-url.ts

@@ -0,0 +1,18 @@
+import { readEnv } from "./require-env";
+
+export interface PublicBaseUrlFromEnvOptions {
+    /** Env var for public URL override (e.g. `STORAGE_PUBLIC_URL`). */
+    envKey: string;
+    env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Public base URL: `envKey` if set (trailing slash stripped), else `http://localhost:{port}`.
+ */
+export function publicBaseUrlFromEnv(port: number, options: PublicBaseUrlFromEnvOptions): string {
+    const configured = readEnv(options.envKey, options.env ?? process.env);
+    if (configured != null) {
+        return configured.replace(/\/$/, "");
+    }
+    return `http://localhost:${port}`;
+}

package/src/node/env/require-env.ts

@@ -0,0 +1,15 @@
+export function readEnv(name: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+    const value = env[name]?.trim();
+    if (value == null || value === "") {
+        return undefined;
+    }
+    return value;
+}
+
+export function requireEnv(name: string, env: NodeJS.ProcessEnv = process.env): string {
+    const value = readEnv(name, env);
+    if (value == null) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}

package/src/node/fs/json-state-store.ts

@@ -0,0 +1,97 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export type JsonStatePatch<T extends object, NK extends keyof T> = Partial<Omit<T, NK>> & {
+    [K in NK]?: T[K] extends object ? Partial<T[K]> : T[K];
+};
+
+export interface JsonFileStateStore<T extends object, NK extends keyof T = never> {
+    read(): Promise<T>;
+    write(patch: JsonStatePatch<T, NK>): Promise<T>;
+    reset(): Promise<T>;
+}
+
+export interface CreateJsonFileStateStoreOptions<T extends object, NK extends keyof T = never> {
+    filePath: string;
+    defaultState: T;
+    /** Top-level keys shallow-merged one level deep on read and write. */
+    nestedKeys?: NK[];
+    /** When set, assigned `new Date().toISOString()` on write and reset. */
+    updatedAtKey?: keyof T;
+}
+
+function mergeWithNested<T extends object>(
+    defaults: T,
+    current: Partial<T> | undefined,
+    patch: Partial<T>,
+    nestedKeys: (keyof T)[],
+): T {
+    const merged = {
+        ...defaults,
+        ...current,
+        ...patch,
+    } as T;
+
+    for (const key of nestedKeys) {
+        const defaultNested = defaults[key];
+        if (defaultNested != null && typeof defaultNested === "object") {
+            (merged as Record<keyof T, unknown>)[key] = {
+                ...defaultNested,
+                ...(current?.[key] as object | undefined),
+                ...(patch[key] as object | undefined),
+            };
+        }
+    }
+
+    return merged;
+}
+
+async function atomicWriteJson(filePath: string, data: unknown): Promise<void> {
+    await mkdir(dirname(filePath), { recursive: true });
+    const content = `${JSON.stringify(data, null, 2)}\n`;
+    const tempPath = `${filePath}.${process.pid}.tmp`;
+    await writeFile(tempPath, content, "utf8");
+    await rename(tempPath, filePath);
+}
+
+/** JSON file-backed state with optional nested key merge and atomic writes. */
+export function createJsonFileStateStore<T extends object, NK extends keyof T = never>(
+    options: CreateJsonFileStateStoreOptions<T, NK>,
+): JsonFileStateStore<T, NK> {
+    const { filePath, defaultState, nestedKeys = [] as NK[], updatedAtKey } = options;
+
+    function touchUpdatedAt(state: T): T {
+        if (updatedAtKey == null) {
+            return state;
+        }
+        return {
+            ...state,
+            [updatedAtKey]: new Date().toISOString(),
+        };
+    }
+
+    return {
+        async read(): Promise<T> {
+            try {
+                const raw = await readFile(filePath, "utf8");
+                const parsed = JSON.parse(raw) as Partial<T>;
+                return mergeWithNested(defaultState, parsed, {}, nestedKeys);
+            } catch {
+                return { ...defaultState };
+            }
+        },
+
+        async write(patch: JsonStatePatch<T, NK>): Promise<T> {
+            const current = await this.read();
+            const next = touchUpdatedAt(mergeWithNested(defaultState, current, patch as Partial<T>, nestedKeys));
+            await atomicWriteJson(filePath, next);
+            return next;
+        },
+
+        async reset(): Promise<T> {
+            const next = touchUpdatedAt({ ...defaultState });
+            await atomicWriteJson(filePath, next);
+            return next;
+        },
+    };
+}

package/src/node/fs/read-source-file.ts

@@ -0,0 +1,75 @@
+import { access, readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { sha256Hex } from "../../shared/utils/sha256";
+
+export interface SourceFilePayload {
+    absolutePath: string;
+    buffer: ArrayBuffer;
+    size: number;
+    sha256: string;
+}
+
+export interface ReadAndVerifySourceFileOptions {
+    /** When set, digest must match or an error is thrown. */
+    expectedSha256?: string;
+    /** Reject files larger than this many bytes. */
+    maxBytes?: number;
+    /** When false, allow zero-byte files (default rejects empty). */
+    allowEmpty?: boolean;
+}
+
+/** Copy a Node.js Buffer view to a standalone ArrayBuffer. */
+export function nodeBufferToArrayBuffer(nodeBuffer: Buffer): ArrayBuffer {
+    return nodeBuffer.buffer.slice(nodeBuffer.byteOffset, nodeBuffer.byteOffset + nodeBuffer.byteLength) as ArrayBuffer;
+}
+
+/** Read a local file with basic validation and SHA-256 digest. */
+export async function readAndVerifySourceFile(
+    filePath: string,
+    options: ReadAndVerifySourceFileOptions = {},
+): Promise<SourceFilePayload> {
+    const absolutePath = resolve(filePath);
+    const allowEmpty = options.allowEmpty === true;
+
+    try {
+        await access(absolutePath);
+    } catch {
+        throw new Error(`Source file not found: ${absolutePath}`);
+    }
+
+    const fileStat = await stat(absolutePath);
+    if (!fileStat.isFile()) {
+        throw new Error(`Source path is not a file: ${absolutePath}`);
+    }
+    if (!allowEmpty && fileStat.size <= 0) {
+        throw new Error(`Source file is empty: ${absolutePath}`);
+    }
+    if (options.maxBytes != null && fileStat.size > options.maxBytes) {
+        throw new Error(`Source file exceeds maxBytes (${fileStat.size} > ${options.maxBytes}): ${absolutePath}`);
+    }
+
+    const nodeBuffer = await readFile(absolutePath);
+    const buffer = nodeBufferToArrayBuffer(nodeBuffer);
+
+    if (buffer.byteLength !== fileStat.size) {
+        throw new Error(
+            `Source file size mismatch after read (${buffer.byteLength} !== ${fileStat.size}): ${absolutePath}`,
+        );
+    }
+
+    const digest = await sha256Hex(buffer);
+
+    if (options.expectedSha256 != null && digest.toLowerCase() !== options.expectedSha256.toLowerCase()) {
+        throw new Error(
+            `Source file SHA-256 mismatch (expected ${options.expectedSha256}, got ${digest}): ${absolutePath}`,
+        );
+    }
+
+    return {
+        absolutePath,
+        buffer,
+        size: buffer.byteLength,
+        sha256: digest,
+    };
+}

package/src/node/node-liveness.ts

@@ -0,0 +1,80 @@
+import { type Node, NodeStatus } from "./node.interface";
+
+export interface TaskNodeLivenessFreshest {
+    nodeId: string;
+    status: string;
+    lastHeartBeat: string;
+    ageMs: number;
+}
+
+export interface TaskNodeLivenessReport {
+    healthy: boolean;
+    staleMs: number;
+    /** BUSY nodes with numeric heartbeat after {@link EvaluateBusyNodeLivenessOptions.excludeNodeId}. */
+    busyWorkerCount: number;
+    /** Subset of candidates with heartbeat age < staleMs. */
+    freshWorkerCount: number;
+    freshest: TaskNodeLivenessFreshest | null;
+}
+
+export interface EvaluateBusyNodeLivenessOptions {
+    staleMs: number;
+    now?: number;
+    /** Omit this node id (e.g. supervisor self). */
+    excludeNodeId?: string;
+    /**
+     * When true, pick freshest only among peers already within staleMs (supervisor spawn guard).
+     * When false, pick freshest among all BUSY peers then compare age to staleMs (observability).
+     */
+    onlyFreshCandidates?: boolean;
+}
+
+function isBusyWithHeartbeat(node: Node): boolean {
+    return node.details.status === NodeStatus.BUSY && typeof node.details.lastHeartBeat === "number";
+}
+
+/** Evaluate TaskNode liveness from a scanned node list (no I/O). */
+export function evaluateBusyNodeLiveness(
+    nodes: Node[],
+    options: EvaluateBusyNodeLivenessOptions,
+): TaskNodeLivenessReport {
+    const now = options.now ?? Date.now();
+    const { staleMs, excludeNodeId, onlyFreshCandidates = false } = options;
+
+    const candidates = nodes.filter(
+        (node) => (excludeNodeId == null || node.id !== excludeNodeId) && isBusyWithHeartbeat(node),
+    );
+
+    const busyWorkerCount = candidates.length;
+    const freshCandidates = candidates.filter((node) => now - node.details.lastHeartBeat < staleMs);
+    const freshWorkerCount = freshCandidates.length;
+
+    const pool = onlyFreshCandidates ? freshCandidates : candidates;
+
+    const freshestNode = pool.reduce<Node | null>((best, node) => {
+        if (best == null) {
+            return node;
+        }
+        return node.details.lastHeartBeat > best.details.lastHeartBeat ? node : best;
+    }, null);
+
+    const ageMs = freshestNode == null ? Number.POSITIVE_INFINITY : now - freshestNode.details.lastHeartBeat;
+
+    const healthy = onlyFreshCandidates ? freshestNode != null : freshestNode != null && ageMs < staleMs;
+
+    return {
+        healthy,
+        staleMs,
+        busyWorkerCount,
+        freshWorkerCount,
+        freshest:
+            freshestNode == null
+                ? null
+                : {
+                      nodeId: freshestNode.id,
+                      status: freshestNode.details.status,
+                      lastHeartBeat: new Date(freshestNode.details.lastHeartBeat).toISOString(),
+                      ageMs,
+                  },
+    };
+}