target-supabase-sdk 0.1.9 → 0.2.1

package/src/node/process/managed-child-processes.ts

@@ -0,0 +1,121 @@
+import type { ChildProcess } from "node:child_process";
+import { resolve } from "node:path";
+import type { LoggerWithScope } from "../../shared/log";
+import { isChildProcessRunning, spawnTsxChild } from "./process-spawn";
+
+export interface ManagedChildProcessesOptions {
+    projectRoot: string;
+    preloadModules?: readonly string[];
+    /** SIGTERM -> wait -> SIGKILL delay (default 5000 ms). */
+    graceMs?: number;
+    logger?: Pick<LoggerWithScope, "info" | "warn" | "error">;
+}
+
+export interface SpawnChildResult {
+    child: ChildProcess;
+    /** false when an equivalent label was already running. */
+    created: boolean;
+}
+
+export interface StopAllChildrenOptions {
+    /** PIDs to SIGTERM when not tracked by this registry (cross-process cleanup). */
+    extraPids?: readonly number[];
+}
+
+/**
+ * Process-local registry for tsx child processes (supervisor, worker, etc.).
+ * Each OS process has its own instance - do not expect cross-process PID tracking.
+ */
+export class ManagedChildProcesses {
+    private readonly projectRoot: string;
+    private readonly preloadModules: readonly string[];
+    private readonly graceMs: number;
+    private readonly logger?: Pick<LoggerWithScope, "info" | "warn" | "error">;
+    private readonly byLabel = new Map<string, ChildProcess>();
+
+    constructor(options: ManagedChildProcessesOptions) {
+        this.projectRoot = options.projectRoot;
+        this.preloadModules = options.preloadModules ?? [];
+        this.graceMs = options.graceMs ?? 5_000;
+        this.logger = options.logger;
+    }
+
+    get(label: string): ChildProcess | null {
+        return this.byLabel.get(label) ?? null;
+    }
+
+    getRunning(label: string): ChildProcess | null {
+        const child = this.byLabel.get(label);
+        return isChildProcessRunning(child) ? child : null;
+    }
+
+    runningLabels(): string[] {
+        return [...this.byLabel.entries()]
+            .filter((entry): entry is [string, ChildProcess] => isChildProcessRunning(entry[1]))
+            .map(([label]) => label);
+    }
+
+    spawn(label: string, entryScript: string): SpawnChildResult {
+        const existing = this.getRunning(label);
+        if (existing != null) {
+            return { child: existing, created: false };
+        }
+
+        const child = spawnTsxChild({
+            projectRoot: this.projectRoot,
+            entryScript,
+            preloadModules: this.preloadModules,
+        });
+
+        child.on("exit", (code, signal) => {
+            this.logger?.info("child exited", { topic: "process", data: { label, code, signal } });
+            const current = this.byLabel.get(label);
+            if (current === child) {
+                this.byLabel.delete(label);
+            }
+        });
+
+        this.byLabel.set(label, child);
+
+        this.logger?.info("child started", {
+            topic: "process",
+            data: {
+                label,
+                pid: child.pid,
+                script: resolve(this.projectRoot, entryScript),
+            },
+        });
+
+        return { child, created: true };
+    }
+
+    async stopAll(options?: StopAllChildrenOptions): Promise<void> {
+        const tracked = [...this.byLabel.values()].filter((child) => isChildProcessRunning(child));
+
+        await Promise.all(tracked.map((child) => this.stopChild(child)));
+
+        const extraPids = options?.extraPids ?? [];
+        for (const pid of extraPids) {
+            if (pid == null || tracked.some((child) => child.pid === pid)) {
+                continue;
+            }
+            try {
+                process.kill(pid, "SIGTERM");
+            } catch {
+                // already exited
+            }
+        }
+    }
+
+    private stopChild(child: ChildProcess): Promise<void> {
+        return new Promise((resolvePromise) => {
+            child.once("exit", () => resolvePromise());
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (isChildProcessRunning(child)) {
+                    child.kill("SIGKILL");
+                }
+            }, this.graceMs);
+        });
+    }
+}

package/src/node/process/process-spawn.ts

@@ -0,0 +1,61 @@
+import { type ChildProcess, type StdioOptions, spawn } from "node:child_process";
+
+export interface BuildNodeImportArgsInput {
+    /** Relative `--import` paths (e.g. `./scripts/preload-env.mjs`). */
+    preloadModules?: readonly string[];
+    /** When true (default), inserts `--import tsx` before the entry script. */
+    useTsx?: boolean;
+    /** Entry script relative to `projectRoot` when spawning. */
+    entryScript: string;
+}
+
+/**
+ * Build argv for `node --import … --import tsx <entry>`.
+ * Use **relative** preload paths with `cwd: projectRoot` — Node 24 on Windows rejects
+ * absolute paths like `D:\…` for `--import` (ESM URL scheme error).
+ */
+export function buildNodeImportArgs(input: BuildNodeImportArgsInput): string[] {
+    const preloadModules = input.preloadModules ?? [];
+    const useTsx = input.useTsx ?? true;
+    const args: string[] = [];
+
+    for (const modulePath of preloadModules) {
+        args.push("--import", modulePath);
+    }
+    if (useTsx) {
+        args.push("--import", "tsx");
+    }
+    args.push(input.entryScript);
+    return args;
+}
+
+export interface SpawnTsxChildOptions {
+    projectRoot: string;
+    entryScript: string;
+    preloadModules?: readonly string[];
+    useTsx?: boolean;
+    env?: NodeJS.ProcessEnv;
+    stdio?: StdioOptions;
+}
+
+/** Spawn `node` with preload chain + tsx + TypeScript entry (relative to projectRoot). */
+export function spawnTsxChild(options: SpawnTsxChildOptions): ChildProcess {
+    return spawn(
+        process.execPath,
+        buildNodeImportArgs({
+            preloadModules: options.preloadModules,
+            useTsx: options.useTsx,
+            entryScript: options.entryScript,
+        }),
+        {
+            cwd: options.projectRoot,
+            env: options.env ?? process.env,
+            stdio: options.stdio ?? "inherit",
+            shell: false,
+        },
+    );
+}
+
+export function isChildProcessRunning(child: ChildProcess | null | undefined): child is ChildProcess {
+    return child != null && child.exitCode == null && !child.killed;
+}

package/src/node/readiness/index.ts

@@ -0,0 +1,20 @@
+export type { PollUntilOptions } from "./poll-until";
+export { pollUntil } from "./poll-until";
+export type { ReadinessCheck, ReadinessCheckResult, ReadinessReport } from "./readiness.types";
+export type {
+    PathsExistCheckOptions,
+    RequiredEnvCheckOptions,
+    SupabaseReachableCheckOptions,
+} from "./readiness-checks";
+export {
+    createPathsExistCheck,
+    createRequiredEnvCheck,
+    createSupabaseReachableCheck,
+} from "./readiness-checks";
+export { runReadinessChecks } from "./run-readiness-checks";
+export type {
+    ServiceReadyGate,
+    ServiceReadySnapshot,
+    WaitForServiceReadyOptions,
+} from "./service-ready-gate";
+export { waitForServiceReady } from "./service-ready-gate";

package/src/node/readiness/poll-until.ts

@@ -0,0 +1,27 @@
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export interface PollUntilOptions {
+    timeoutMs: number;
+    intervalMs?: number;
+    until: () => boolean | Promise<boolean>;
+}
+
+/**
+ * Poll `until()` until it returns true or `timeoutMs` elapses.
+ * @throws Error on timeout
+ */
+export async function pollUntil(options: PollUntilOptions): Promise<void> {
+    const intervalMs = options.intervalMs ?? 500;
+    const deadline = Date.now() + options.timeoutMs;
+
+    while (Date.now() < deadline) {
+        if (await options.until()) {
+            return;
+        }
+        await sleep(intervalMs);
+    }
+
+    throw new Error(`pollUntil timeout after ${options.timeoutMs}ms`);
+}

package/src/node/readiness/readiness-checks.ts

@@ -0,0 +1,79 @@
+import { access } from "node:fs/promises";
+import { scanTargetList } from "../../core.api";
+import { requireEnv } from "../env/require-env";
+import type { ReadinessCheck, ReadinessCheckResult } from "./readiness.types";
+
+export interface RequiredEnvCheckOptions {
+    env?: NodeJS.ProcessEnv;
+}
+
+/** Factory: all listed env keys must be non-empty. */
+export function createRequiredEnvCheck(
+    name: string,
+    keys: string[],
+    options?: RequiredEnvCheckOptions,
+): ReadinessCheck {
+    return () => {
+        const env = options?.env ?? process.env;
+        try {
+            for (const key of keys) {
+                requireEnv(key, env);
+            }
+            return { name, ok: true };
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { name, ok: false, detail: message };
+        }
+    };
+}
+
+export interface PathsExistCheckOptions {
+    /** Detail string when all paths exist (default: last path). */
+    successDetail?: string;
+    /** Detail prefix when a path is missing. */
+    missingDetail?: string;
+}
+
+/** Factory: every path must exist on disk. */
+export function createPathsExistCheck(name: string, paths: string[], options?: PathsExistCheckOptions): ReadinessCheck {
+    return async () => {
+        for (const filePath of paths) {
+            try {
+                await access(filePath);
+            } catch {
+                return {
+                    name,
+                    ok: false,
+                    detail: options?.missingDetail ?? `Missing ${filePath}`,
+                };
+            }
+        }
+
+        const detail = options?.successDetail ?? paths[paths.length - 1] ?? paths.join(", ");
+
+        return { name, ok: true, detail };
+    };
+}
+
+export interface SupabaseReachableCheckOptions {
+    name?: string;
+    category?: string;
+    maxRows?: number;
+}
+
+/** Factory: lightweight Supabase query via {@link scanTargetList}. */
+export function createSupabaseReachableCheck(options?: SupabaseReachableCheckOptions): ReadinessCheck {
+    const name = options?.name ?? "supabase_connectivity";
+    const category = options?.category ?? "node";
+    const maxRows = options?.maxRows ?? 1;
+
+    return async (): Promise<ReadinessCheckResult> => {
+        try {
+            await scanTargetList({ category, maxRows });
+            return { name, ok: true };
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { name, ok: false, detail: message };
+        }
+    };
+}

package/src/node/readiness/readiness.types.ts

@@ -0,0 +1,13 @@
+export interface ReadinessCheckResult {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+
+export interface ReadinessReport {
+    ok: boolean;
+    checks: ReadinessCheckResult[];
+    message: string | null;
+}
+
+export type ReadinessCheck = () => ReadinessCheckResult | Promise<ReadinessCheckResult>;

package/src/node/readiness/run-readiness-checks.ts

@@ -0,0 +1,20 @@
+import type { ReadinessCheck, ReadinessReport } from "./readiness.types";
+
+function formatFailureMessage(checks: ReadinessReport["checks"]): string {
+    return checks
+        .filter((check) => !check.ok)
+        .map((check) => `${check.name}: ${check.detail ?? "failed"}`)
+        .join("; ");
+}
+
+/** Run checks in order and aggregate into a {@link ReadinessReport}. */
+export async function runReadinessChecks(checks: ReadinessCheck[]): Promise<ReadinessReport> {
+    const results = await Promise.all(checks.map((check) => check()));
+    const failed = results.filter((check) => !check.ok);
+
+    return {
+        ok: failed.length === 0,
+        checks: results,
+        message: failed.length === 0 ? null : formatFailureMessage(results),
+    };
+}

package/src/node/readiness/service-ready-gate.ts

@@ -0,0 +1,65 @@
+import type { LoggerWithScope } from "../../shared/log";
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export interface ServiceReadySnapshot {
+    failed: boolean;
+    ready: boolean;
+    failureMessage?: string | null;
+    /** Logged on success (e.g. worker tasks, pid). */
+    readyDetail?: unknown;
+}
+
+/** Cross-process ready gate — service implements by reading shared state (file, RPC, …). */
+export interface ServiceReadyGate {
+    read(): Promise<ServiceReadySnapshot>;
+}
+
+export interface WaitForServiceReadyOptions {
+    timeoutMs: number;
+    pollMs?: number;
+    logger?: Pick<LoggerWithScope, "info">;
+    /** Default failure message when gate.read().failureMessage is empty. */
+    failureMessage?: string;
+    formatTimeoutError?: (last: ServiceReadySnapshot, timeoutMs: number) => string;
+}
+
+/**
+ * Poll {@link ServiceReadyGate} until ready, fail fast on `failed`, or timeout.
+ * Returns the final ready snapshot.
+ */
+export async function waitForServiceReady(
+    gate: ServiceReadyGate,
+    options: WaitForServiceReadyOptions,
+): Promise<ServiceReadySnapshot> {
+    const pollMs = options.pollMs ?? 500;
+    const defaultFailureMessage = options.failureMessage ?? "Readiness checks failed";
+    const deadline = Date.now() + options.timeoutMs;
+    let last: ServiceReadySnapshot = { failed: false, ready: false };
+
+    while (Date.now() < deadline) {
+        last = await gate.read();
+
+        if (last.failed) {
+            throw new Error(last.failureMessage ?? defaultFailureMessage);
+        }
+
+        if (last.ready) {
+            options.logger?.info("service ready", {
+                topic: "readiness",
+                data: last.readyDetail ?? {},
+            });
+            return last;
+        }
+
+        await sleep(pollMs);
+    }
+
+    const message =
+        options.formatTimeoutError?.(last, options.timeoutMs) ??
+        `Service ready timeout after ${options.timeoutMs}ms (failed=${last.failed}, ready=${last.ready})`;
+
+    throw new Error(message);
+}

package/src/node.ts

@@ -0,0 +1,153 @@
+/**
+ * Node.js runtime entry — browser API plus local FS / worker orchestration.
+ *
+ * import { TaskManager, RepoManager, TaskNode } from "target-supabase-sdk/node";
+ */
+
+export * from "./browser";
+export * from "./command/command.api";
+export * from "./command/command.interface";
+export type {
+    EnvIntOptions,
+    EnvNumberOptions,
+    InitSupabaseFromStandardEnvOptions,
+    LoadEnvFilesOptions,
+    PublicBaseUrlFromEnvOptions,
+} from "./node/env";
+export {
+    envBool,
+    envInt,
+    envMs,
+    envNumber,
+    envPort,
+    initSupabaseFromStandardEnv,
+    loadEnvFiles,
+    parseEnvFile,
+    parseEnvLine,
+    publicBaseUrlFromEnv,
+    readEnv,
+    requireEnv,
+    resolveProjectRootByPackageName,
+    resolveProjectRootFromModule,
+} from "./node/env";
+export type {
+    CreateJsonFileStateStoreOptions,
+    JsonFileStateStore,
+    JsonStatePatch,
+} from "./node/fs/json-state-store";
+export { createJsonFileStateStore } from "./node/fs/json-state-store";
+export type {
+    ReadAndVerifySourceFileOptions,
+    SourceFilePayload,
+} from "./node/fs/read-source-file";
+export {
+    nodeBufferToArrayBuffer,
+    readAndVerifySourceFile,
+} from "./node/fs/read-source-file";
+export { BaseNodeRuntime } from "./node/node-runtime.base";
+export type {
+    BuildNodeImportArgsInput,
+    ManagedChildProcessesOptions,
+    SpawnChildResult,
+    SpawnTsxChildOptions,
+    StopAllChildrenOptions,
+} from "./node/process";
+export {
+    buildNodeImportArgs,
+    isChildProcessRunning,
+    ManagedChildProcesses,
+    spawnTsxChild,
+} from "./node/process";
+export type {
+    PathsExistCheckOptions,
+    PollUntilOptions,
+    ReadinessCheck,
+    ReadinessCheckResult,
+    ReadinessReport,
+    RequiredEnvCheckOptions,
+    ServiceReadyGate,
+    ServiceReadySnapshot,
+    SupabaseReachableCheckOptions,
+    WaitForServiceReadyOptions,
+} from "./node/readiness";
+export {
+    createPathsExistCheck,
+    createRequiredEnvCheck,
+    createSupabaseReachableCheck,
+    pollUntil,
+    runReadinessChecks,
+    waitForServiceReady,
+} from "./node/readiness";
+export { RepoManager } from "./repo/repo-manager";
+export {
+    disableLogPersist,
+    enableLogPersist,
+    ensureLogPersistFromEnv,
+    getLogPersistStats,
+    logPersistEnabledFromEnv,
+    resolveLogPersistRegistryPath,
+    snapshotLogPersistReady,
+    validateLogPersistPreloadEnv,
+    waitForLogPersistReady,
+} from "./shared/log/enable-log-persist";
+export type {
+    EnableLogPersistOptions,
+    EnsureLogPersistFromEnvOptions,
+    LogPersistLane,
+    LogPersistReadySnapshot,
+    LogPersistStats,
+    WaitForLogPersistReadyOptions,
+} from "./shared/log/log-persist.interface";
+export type {
+    BootstrapLocalTasksResult,
+    BootstrapLocalTasksStatus,
+    ExecutableTaskFn,
+    PrepareTaskParams,
+    PrepareTaskResponse,
+    RegisterTasksOptions,
+    RegisterTasksResult,
+    TaskFn,
+    TaskLocalPackageConfig,
+    TaskRepoContext,
+    TaskRepoScriptDetails,
+    TaskRepoScriptRecord,
+    TaskRunnerRootConfig,
+    TaskRunResult,
+} from "./task/task-manager";
+export {
+    TASK_LOCAL_PACKAGE_CONFIG_FILENAME,
+    TASK_REPO_SCRIPT_CATEGORY,
+    TASK_RUNNER_CONFIG_DIR,
+    TASK_RUNNER_ROOT_CONFIG_FILENAME,
+    TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH,
+    TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH,
+    TaskManager,
+} from "./task/task-manager";
+export { TaskNode } from "./task/task-node";
+export type { PostTaskPayload } from "./task/task-post.api";
+export { postTaskWithValidation } from "./task/task-post-validated.api";
+export type {
+    TaskRepoValidationFailureReason,
+    ValidateTaskRepoAndParamsInput,
+    ValidateTaskRepoAndParamsResult,
+} from "./task/task-repo-validation";
+export {
+    TaskRepoValidation,
+    validateTaskRepoAndParams,
+} from "./task/task-repo-validation";
+export * from "./trigger/trigger.api";
+export {
+    LOG_TOPIC_TRIGGER,
+    TRIGGER_LOOP_INTERVAL_MS,
+    TRIGGER_RUNNER_DEFAULT_RETRY_COUNT,
+    TRIGGER_RUNNER_DEFAULT_RETRY_DELAY_MS,
+} from "./trigger/trigger.constant";
+export type {
+    RegisterTriggerRunnerOptions,
+    TriggerNodeOptions,
+    TriggerRunnerContext,
+    TriggerRunnerFn,
+} from "./trigger/trigger.interface";
+export * from "./trigger/trigger.interface";
+export { TriggerManager } from "./trigger/trigger-manager";
+export { TriggerNode } from "./trigger/trigger-node";

package/src/parcel/chunk-fetch-registry.ts

@@ -0,0 +1,96 @@
+import { isHttpUrl, resolveFetchUrl } from "../shared/utils/fetch-url";
+import { isLocalFilesystemPath, parseProviderPrefixedUrl } from "./chunk-url.utils";
+
+interface ChunkResolver {
+    provider: string;
+    matches(url: string): boolean;
+    resolve(locator: string): Promise<ArrayBuffer>;
+}
+
+/** Provider module subset used for opaque {@link Chunk} restore. */
+export interface ChunkResolveProvider {
+    readonly provider: string;
+    resolveChunk?(locator: string): Promise<ArrayBuffer>;
+    matchesOpaqueUrl?(url: string): boolean;
+}
+
+const resolvers = new Map<string, ChunkResolver>();
+
+function registerChunkResolver(resolver: ChunkResolver): void {
+    resolvers.set(resolver.provider, resolver);
+}
+
+/** Register a provider's chunk resolver (call when the provider module loads). */
+export function registerProviderChunkResolver(module: ChunkResolveProvider): void {
+    if (module.resolveChunk == null) {
+        return;
+    }
+
+    const resolveChunk = module.resolveChunk;
+
+    registerChunkResolver({
+        provider: module.provider,
+        matches(url: string) {
+            const prefixed = parseProviderPrefixedUrl(url);
+            if (prefixed != null) {
+                return prefixed.provider === module.provider;
+            }
+            return module.matchesOpaqueUrl?.(url) === true;
+        },
+        resolve(locator: string) {
+            const prefixed = parseProviderPrefixedUrl(locator);
+            const opaque = prefixed?.provider === module.provider ? prefixed.locator : locator;
+            return resolveChunk(opaque);
+        },
+    });
+}
+
+async function resolveOpaqueUrl(url: string): Promise<ArrayBuffer> {
+    const prefixed = parseProviderPrefixedUrl(url);
+    if (prefixed != null) {
+        const resolver = resolvers.get(prefixed.provider);
+        if (resolver == null) {
+            throw new Error(`No chunk resolver registered for provider: ${prefixed.provider}`);
+        }
+        return resolver.resolve(prefixed.locator);
+    }
+
+    const matches = [...resolvers.values()].filter((entry) => entry.matches(url));
+    if (matches.length === 1) {
+        return matches[0].resolve(url);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Ambiguous chunk url (${url}); use provider-prefixed form e.g. telegram:${url.slice(0, 12)}…`);
+    }
+
+    const registered = [...resolvers.keys()].join(", ") || "(none)";
+    throw new Error(`No chunk resolver for opaque url (${url.slice(0, 24)}…). Registered: ${registered}`);
+}
+
+/**
+ * Patch global fetch so ParcelManager.reassemble can resolve opaque chunk locators.
+ * HTTP URLs use the original fetch (S3 presigned, etc.).
+ */
+export function installChunkFetchRegistry(): () => void {
+    const originalFetch = globalThis.fetch.bind(globalThis);
+
+    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+        const url = resolveFetchUrl(input);
+        if (isHttpUrl(url)) {
+            return originalFetch(input, init);
+        }
+        if (isLocalFilesystemPath(url)) {
+            throw new Error(
+                `Chunk fetch registry: local path not supported (${url}). ` +
+                    "Use a local provider module or parcel-restore-local.",
+            );
+        }
+
+        const buffer = await resolveOpaqueUrl(url);
+        return new Response(buffer, { headers: { "Content-Type": "application/octet-stream" } });
+    }) as typeof fetch;
+
+    return () => {
+        globalThis.fetch = originalFetch;
+    };
+}

package/src/parcel/chunk-url.utils.ts

@@ -0,0 +1,30 @@
+import { isHttpUrl } from "../shared/utils/fetch-url";
+
+export function isLocalFilesystemPath(url: string): boolean {
+    if (url.startsWith("file://")) {
+        return true;
+    }
+    return /^[a-zA-Z]:[\\/]/.test(url) || url.startsWith("\\\\") || url.startsWith("/");
+}
+
+/** Opaque chunk locator - not HTTP and not a local path (e.g. Telegram file_id). */
+export function isOpaqueChunkUrl(url: string): boolean {
+    return !isHttpUrl(url) && !isLocalFilesystemPath(url);
+}
+
+/** `provider:opaque` scheme (e.g. `telegram:BQACAg...`). */
+export function parseProviderPrefixedUrl(url: string): { provider: string; locator: string } | null {
+    const match = /^([a-z][a-z0-9_-]*):(.+)$/i.exec(url);
+    if (match == null) {
+        return null;
+    }
+    const provider = match[1].toLowerCase();
+    const locator = match[2].trim();
+    if (locator === "") {
+        return null;
+    }
+    if (provider === "http" || provider === "https" || provider === "file") {
+        return null;
+    }
+    return { provider, locator };
+}