target-supabase-sdk 0.2.0 → 0.2.2

package/src/shared/log/log-scope.ts

@@ -8,11 +8,17 @@ export interface LogScope {
     labels?: Readonly<Record<string, string>>;
 }
 
-/** Partial update for {@link LogScope} / {@link applyScopePatch}. */
+/** Partial update for {@link patchScope}. */
 export type LogScopePatch = Partial<Omit<LogScope, "labels">> & {
     labels?: Record<string, string>;
 };
 
+/** Fields allowed on {@link LoggerWithScope.resetScope} — no trace identity changes. */
+export type LoggerResetScopePatch = {
+    module?: string;
+    labels?: Record<string, string>;
+};
+
 export type LogScopeInput = LogScopePatch & Pick<LogScope, "module">;
 
 interface NormalizeScopeOptions {
@@ -20,9 +26,20 @@ interface NormalizeScopeOptions {
     generateTraceId?: boolean;
 }
 
+/** Input for {@link patchScope}. */
+export type PatchScopeInput = {
+    scope: LogScope;
+    patch: LogScopePatch;
+    /**
+     * When `false` (default), `patch.traceId` / `patch.traceParentId` are ignored.
+     * New spans: use {@link createScope}.
+     */
+    allowTraceMutation?: boolean;
+};
+
 function mergeLabels(
     base?: Readonly<Record<string, string>>,
-    patch?: Record<string, string>
+    patch?: Record<string, string>,
 ): Record<string, string> | undefined {
     const merged: Record<string, string> = { ...base, ...patch };
     return Object.keys(merged).length > 0 ? merged : undefined;
@@ -44,64 +61,47 @@ export function normalizeScope(input: LogScopeInput, options?: NormalizeScopeOpt
     };
 }
 
-/** Input for {@link createRootScope}. */
-export type CreateRootScopeInput = {
+/** Input for {@link createScope}. */
+export type CreateScopeInput = {
     module: string;
-    traceId?: string;
-    labels?: Record<string, string>;
-    traceParentId?: string | null;
-};
-
-/** Root scope: traceParentId defaults to null. */
-export function createRootScope(input: CreateRootScopeInput): LogScope {
-    return normalizeScope(
-        {
-            module: input.module,
-            traceId: input.traceId,
-            traceParentId: input.traceParentId ?? null,
-            labels: input.labels,
-        },
-        { generateTraceId: true }
-    );
-}
-
-/** Input for {@link createChildScope}. */
-export type CreateChildScopeInput = {
-    module: string;
-    parent: LogScope;
-    traceId?: string;
+    traceId: string;
     traceParentId?: string | null;
     labels?: Record<string, string>;
+    /** When set, default traceParentId to parent.traceId and merge labels. */
+    parent?: LogScope;
 };
 
-/** Child scope: parent link defaults to parent.traceId; labels merge with parent. */
-export function createChildScope(input: CreateChildScopeInput): LogScope {
+/** Build a scope; optional parent links trace chain and merges labels. */
+export function createScope(input: CreateScopeInput): LogScope {
     const { module, parent, traceId, traceParentId, labels } = input;
-    return normalizeScope(
-        {
-            module,
-            traceId,
-            traceParentId: traceParentId ?? parent.traceId,
-            labels: mergeLabels(parent.labels, labels),
-        },
-        { generateTraceId: true }
-    );
+    return normalizeScope({
+        module,
+        traceId,
+        traceParentId: traceParentId ?? (parent != null ? parent.traceId : null),
+        labels: parent != null ? mergeLabels(parent.labels, labels) : mergeLabels(undefined, labels),
+    });
 }
 
-/** Same trace chain, different module (e.g. prepareTask vs executeTask). */
-export function withModule(scope: LogScope, module: string): LogScope {
-    return { ...scope, module };
-}
+/** Merge patch into scope (labels deep-merge). Returns a new scope. */
+export function patchScope(input: PatchScopeInput): LogScope {
+    const { scope, patch, allowTraceMutation = false } = input;
+    const traceId = allowTraceMutation && patch.traceId != null && patch.traceId !== "" ? patch.traceId : scope.traceId;
+    const traceParentId =
+        allowTraceMutation && patch.traceParentId !== undefined ? patch.traceParentId : scope.traceParentId;
 
-/** Merge patch into scope (labels deep-merge). */
-export function applyScopePatch(scope: LogScope, patch: LogScopePatch): LogScope {
     return normalizeScope({
         module: patch.module ?? scope.module,
-        traceId: patch.traceId ?? scope.traceId,
-        traceParentId: patch.traceParentId !== undefined ? patch.traceParentId : scope.traceParentId,
+        traceId,
+        traceParentId,
         labels: mergeLabels(scope.labels, patch.labels),
     });
 }
+
+/** Same trace chain, different module (e.g. prepareTask vs executeTask). */
+export function withModule(scope: LogScope, module: string): LogScope {
+    return patchScope({ scope, patch: { module } });
+}
+
 export function formatScopeLabels(labels?: Readonly<Record<string, string>>): string {
     if (labels == null || Object.keys(labels).length === 0) {
         return "--";

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

@@ -69,7 +69,7 @@ export interface ResolveFirstExistingPathOptions {
  */
 export async function resolveFirstExistingPath(
     cwd: string,
-    options: ResolveFirstExistingPathOptions
+    options: ResolveFirstExistingPathOptions,
 ): Promise<string | null> {
     const { explicitPath, candidatePaths } = options;
 

package/src/shared/utils/fetch-url.ts

@@ -0,0 +1,13 @@
+export function resolveFetchUrl(input: string | URL | Request): string {
+    if (typeof input === "string") {
+        return input;
+    }
+    if (input instanceof URL) {
+        return input.href;
+    }
+    return input.url;
+}
+
+export function isHttpUrl(url: string): boolean {
+    return url.startsWith("http://") || url.startsWith("https://");
+}

package/src/shared/utils/network-error.ts

@@ -0,0 +1,152 @@
+export type NetworkErrorKind =
+    | "connect_timeout"
+    | "tls_disconnect"
+    | "connection_refused"
+    | "dns_error"
+    | "socket_closed"
+    | "timeout"
+    | "proxy_error"
+    | "unknown";
+
+export interface ClassifiedNetworkError {
+    kind: NetworkErrorKind;
+    retryable: boolean;
+    code: string;
+    detail: string;
+}
+
+const RETRYABLE_CAUSE_CODES = new Set([
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "ETIMEDOUT",
+    "EPIPE",
+    "EAI_AGAIN",
+]);
+
+function errorCause(error: unknown): { code?: string; message?: string } | undefined {
+    if (error instanceof Error) {
+        return error.cause as { code?: string; message?: string } | undefined;
+    }
+    return undefined;
+}
+
+export function classifyNetworkError(error: unknown): ClassifiedNetworkError {
+    if (!(error instanceof Error)) {
+        return { kind: "unknown", retryable: false, code: "", detail: String(error) };
+    }
+
+    const cause = errorCause(error);
+    const code = cause?.code ?? "";
+    const causeMessage = cause?.message ?? "";
+    const message = error.message;
+
+    const tlsDisconnect =
+        /TLS connection was established/i.test(causeMessage) ||
+        /secure TLS connection/i.test(causeMessage) ||
+        /socket disconnected before secure TLS/i.test(message) ||
+        /socket disconnected before secure TLS/i.test(causeMessage);
+
+    if (tlsDisconnect) {
+        return {
+            kind: "tls_disconnect",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+
+    if (code === "UND_ERR_CONNECT_TIMEOUT" || error.name === "TimeoutError" || error.name === "AbortError") {
+        return {
+            kind: error.name === "AbortError" ? "timeout" : "connect_timeout",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+
+    if (code === "ECONNREFUSED") {
+        return {
+            kind: "connection_refused",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+        return {
+            kind: "dns_error",
+            retryable: code === "EAI_AGAIN",
+            code,
+            detail: causeMessage || message,
+        };
+    }
+
+    if (
+        code === "UND_ERR_SOCKET" ||
+        code === "ECONNRESET" ||
+        code === "EPIPE" ||
+        /socket disconnected/i.test(causeMessage) ||
+        /other side closed/i.test(causeMessage)
+    ) {
+        return {
+            kind: "socket_closed",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+
+    if (RETRYABLE_CAUSE_CODES.has(code)) {
+        return {
+            kind: "proxy_error",
+            retryable: true,
+            code,
+            detail: causeMessage || message,
+        };
+    }
+
+    return {
+        kind: "unknown",
+        retryable: false,
+        code,
+        detail: causeMessage ? `${message}: ${causeMessage}` : message,
+    };
+}
+
+export interface FormatNetworkErrorOptions {
+    /** Extra hint appended (proxy URL, env var name, etc.). */
+    hint?: string;
+}
+
+export function formatNetworkError(error: unknown, label: string, options: FormatNetworkErrorOptions = {}): string {
+    const classified = classifyNetworkError(error);
+    const hint = options.hint ?? "";
+
+    switch (classified.kind) {
+        case "connect_timeout":
+            return `${label}: connect timeout${hint}`;
+        case "tls_disconnect":
+            return `${label}: TLS handshake dropped${hint}. Often transient through proxies — retries may succeed.`;
+        case "connection_refused":
+            return `${label}: connection refused — ${classified.detail}${hint}`;
+        case "dns_error":
+            return `${label}: DNS lookup failed (${classified.code}) — ${classified.detail}`;
+        case "socket_closed":
+            return (
+                `${label}: connection closed mid-request (${classified.code || "socket"}) — ` +
+                `${classified.detail}${hint}`
+            );
+        case "timeout":
+            return `${label}: request timeout — ${classified.detail}${hint}`;
+        case "proxy_error":
+            return `${label}: network/proxy error (${classified.code}) — ${classified.detail}${hint}`;
+        default:
+            return `${label}: ${classified.detail}${hint}`;
+    }
+}

package/src/shared/utils/safe-file-name.ts

@@ -0,0 +1,37 @@
+export interface SanitizeFileNameOptions {
+    /** Max length after sanitization (default 200). */
+    maxLength?: number;
+    /** When set, used instead of throwing on invalid names. */
+    fallback?: string;
+}
+
+function fileBaseName(raw: string): string {
+    const normalized = raw.replace(/\\/g, "/");
+    const parts = normalized.split("/");
+    return parts.at(-1) ?? normalized;
+}
+
+/**
+ * Safe display / storage file name from a browser or filesystem path string.
+ * Strips directory segments and forbidden characters.
+ */
+export function sanitizeFileName(raw: string, options: SanitizeFileNameOptions = {}): string {
+    const maxLength = options.maxLength ?? 200;
+    const base = fileBaseName(raw);
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentionally strip ASCII control chars (0x00–0x1f)
+    const cleaned = base.replace(/[\x00-\x1f<>:"/\\|?*]+/g, "_").trim();
+
+    if (cleaned === "" || cleaned === "." || cleaned === "..") {
+        if (options.fallback != null) {
+            return options.fallback.slice(0, maxLength);
+        }
+        throw new Error("Invalid file name");
+    }
+
+    return cleaned.slice(0, maxLength);
+}
+
+/** Parcel.name / value default — 200 char cap. */
+export function sanitizeParcelFileName(raw: string): string {
+    return sanitizeFileName(raw, { maxLength: 200 });
+}

package/src/shared/utils/sha256.ts

@@ -0,0 +1,15 @@
+function getCrypto(): Crypto {
+    if (typeof globalThis !== "undefined" && globalThis.crypto) {
+        return globalThis.crypto;
+    }
+    throw new Error("sha256Hex: crypto.subtle not available");
+}
+
+/** SHA-256 digest as lowercase hex (browser + Node Web Crypto). */
+export async function sha256Hex(buffer: ArrayBuffer): Promise<string> {
+    const crypto = getCrypto();
+    const hash = await crypto.subtle.digest("SHA-256", buffer);
+    return Array.from(new Uint8Array(hash))
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}

package/src/supabase.ts

@@ -1,143 +1,149 @@
-import { createClient, SupabaseClient } from "@supabase/supabase-js";
+import { createClient, type SupabaseClient } from "@supabase/supabase-js";
 import { logDev, logDevGroup } from "./core.utils";
 
 interface SupabaseConfig {
-  main: {
-    url: string;
-    anonKey: string;
-  };
-  auth: {
-    url: string;
-    anonKey: string;
-  } | null;
+    main: {
+        url: string;
+        anonKey: string;
+    };
+    auth: {
+        url: string;
+        anonKey: string;
+    } | null;
 }
 
 export interface SupabaseInitializerParams {
-  supabaseUrl: string;
-  supabaseAnonKey: string;
-  supabaseNeedAuthUrl?: string;
-  supabaseNeedAuthAnonKey?: string;
+    supabaseUrl: string;
+    supabaseAnonKey: string;
+    supabaseNeedAuthUrl?: string;
+    supabaseNeedAuthAnonKey?: string;
 }
 
-export class SupabaseInitializer {
-  private static instance: SupabaseInitializer;
-  private isInitialized = false;
-  private _mainClient: SupabaseClient | null = null;
-  private _authClient: SupabaseClient | null = null;
+class SupabaseInitializer {
+    private static instance: SupabaseInitializer;
+    private isInitialized = false;
+    private _mainClient: SupabaseClient | null = null;
+    private _authClient: SupabaseClient | null = null;
 
-  private constructor() {}
+    private constructor() {}
 
-  static getInstance(): SupabaseInitializer {
-    if (!SupabaseInitializer.instance) {
-      SupabaseInitializer.instance = new SupabaseInitializer();
-    }
-    return SupabaseInitializer.instance;
-  }
-
-  /**
-   * Initialize Supabase clients
-   */
-  async initialize(
-    params: SupabaseInitializerParams
-  ): Promise<{ supabase: SupabaseClient; supabaseAuth: SupabaseClient | null }> {
-    if (this.isInitialized) {
-      logDev("🚫 Supabase already initialized");
-      return { supabase: this._mainClient!, supabaseAuth: this._authClient };
+    static getInstance(): SupabaseInitializer {
+        if (!SupabaseInitializer.instance) {
+            SupabaseInitializer.instance = new SupabaseInitializer();
+        }
+        return SupabaseInitializer.instance;
     }
 
-    logDev("🔧 Initializing Supabase...");
-
-    // Validate and get environment variables
-    const config = this.validateEnvironmentVariables(params);
-
-    // Create main client
-    this._mainClient = createClient(config.main.url, config.main.anonKey, {
-      // TODO
-      // auth: {
-      //   persistSession: true,
-      //   autoRefreshToken: true,
-      // },
-    });
-
-    // Create auth client if configured
-    if (config.auth) {
-      this._authClient = createClient(config.auth.url, config.auth.anonKey, {
-        // TODO
-        // auth: {
-        //   persistSession: true,
-        //   autoRefreshToken: true,
-        // },
-      });
+    /**
+     * Initialize Supabase clients
+     */
+    async initialize(
+        params: SupabaseInitializerParams,
+    ): Promise<{ supabase: SupabaseClient; supabaseAuth: SupabaseClient | null }> {
+        if (this.isInitialized) {
+            logDev("🚫 Supabase already initialized");
+            return { supabase: this._mainClient!, supabaseAuth: this._authClient };
+        }
+
+        logDev("🔧 Initializing Supabase...");
+
+        // Validate and get environment variables
+        const config = this.validateEnvironmentVariables(params);
+
+        // Create main client
+        this._mainClient = createClient(config.main.url, config.main.anonKey, {
+            // TODO
+            // auth: {
+            //   persistSession: true,
+            //   autoRefreshToken: true,
+            // },
+        });
+
+        // Create auth client if configured
+        if (config.auth) {
+            this._authClient = createClient(config.auth.url, config.auth.anonKey, {
+                // TODO
+                // auth: {
+                //   persistSession: true,
+                //   autoRefreshToken: true,
+                // },
+            });
+        }
+
+        // Log configuration
+        this.logConfiguration(config);
+
+        this.isInitialized = true;
+        logDev("✅ Supabase initialization completed");
+
+        return { supabase: this._mainClient, supabaseAuth: this._authClient };
     }
 
-    // Log configuration
-    this.logConfiguration(config);
-
-    this.isInitialized = true;
-    logDev("✅ Supabase initialization completed");
-
-    return { supabase: this._mainClient, supabaseAuth: this._authClient };
-  }
-
-  private validateEnvironmentVariables({
-    supabaseUrl,
-    supabaseAnonKey,
-    supabaseNeedAuthUrl,
-    supabaseNeedAuthAnonKey,
-  }: SupabaseInitializerParams): SupabaseConfig {
-    const mainUrl = supabaseUrl;
-    const mainAnonKey = supabaseAnonKey;
-    const authUrl = supabaseNeedAuthUrl;
-    const authAnonKey = supabaseNeedAuthAnonKey;
+    private validateEnvironmentVariables({
+        supabaseUrl,
+        supabaseAnonKey,
+        supabaseNeedAuthUrl,
+        supabaseNeedAuthAnonKey,
+    }: SupabaseInitializerParams): SupabaseConfig {
+        const mainUrl = supabaseUrl;
+        const mainAnonKey = supabaseAnonKey;
+        const authUrl = supabaseNeedAuthUrl;
+        const authAnonKey = supabaseNeedAuthAnonKey;
+
+        if (!mainUrl || !mainAnonKey) {
+            throw new Error("Missing required Supabase environment variables: SUPABASE_URL, SUPABASE_ANON_KEY");
+        }
+
+        return {
+            main: { url: mainUrl, anonKey: mainAnonKey },
+            auth: authUrl && authAnonKey ? { url: authUrl, anonKey: authAnonKey } : null,
+        };
+    }
 
-    if (!mainUrl || !mainAnonKey) {
-      throw new Error("Missing required Supabase environment variables: SUPABASE_URL, SUPABASE_ANON_KEY");
+    private logConfiguration(config: SupabaseConfig) {
+        logDevGroup("🔧 Supabase Configuration", () => {
+            console.log("Main URL:", config.main.url);
+            console.log("Auth URL:", config.auth?.url || "Not configured");
+            console.log("Clients:", {
+                main: !!this._mainClient,
+                auth: !!this._authClient,
+            });
+        });
     }
 
-    return {
-      main: { url: mainUrl, anonKey: mainAnonKey },
-      auth: authUrl && authAnonKey ? { url: authUrl, anonKey: authAnonKey } : null,
-    };
-  }
-
-  private logConfiguration(config: SupabaseConfig) {
-    logDevGroup("🔧 Supabase Configuration", () => {
-      console.log("Main URL:", config.main.url);
-      console.log("Auth URL:", config.auth?.url || "Not configured");
-      console.log("Clients:", {
-        main: !!this._mainClient,
-        auth: !!this._authClient,
-      });
-    });
-  }
-
-  getClients() {
-    if (!this.isInitialized) {
-      throw new Error("Supabase not initialized. Call initialize() first.");
+    getClients() {
+        if (!this.isInitialized) {
+            throw new Error("Supabase not initialized. Call initialize() first.");
+        }
+        return { supabase: this._mainClient!, supabaseAuth: this._authClient };
     }
-    return { supabase: this._mainClient!, supabaseAuth: this._authClient };
-  }
 
-  get client(): SupabaseClient {
-    if (!this.isInitialized) {
-      throw new Error("Supabase not initialized. Call initialize() first.");
+    get client(): SupabaseClient {
+        if (!this.isInitialized) {
+            throw new Error("Supabase not initialized. Call initialize() first.");
+        }
+        if (!this._mainClient) {
+            throw new Error("Main Supabase client is null. Initialization may have failed.");
+        }
+        return this._mainClient;
     }
-    if (!this._mainClient) {
-      throw new Error("Main Supabase client is null. Initialization may have failed.");
+
+    get authClient(): SupabaseClient | null {
+        if (!this.isInitialized) {
+            throw new Error("Supabase not initialized. Call initialize() first.");
+        }
+        return this._authClient;
     }
-    return this._mainClient;
-  }
 
-  get authClient(): SupabaseClient | null {
-    if (!this.isInitialized) {
-      throw new Error("Supabase not initialized. Call initialize() first.");
+    reset() {
+        this.isInitialized = false;
+        this._mainClient = null;
+        this._authClient = null;
     }
-    return this._authClient;
-  }
-
-  reset() {
-    this.isInitialized = false;
-    this._mainClient = null;
-    this._authClient = null;
-  }
 }
+
+/** Process-wide holder — import this; class is module-private. */
+export const supabase = SupabaseInitializer.getInstance();
+
+/** Public type for the `supabase` holder instance. */
+export type SupabaseHolder = typeof supabase;