target-supabase-sdk 0.2.3 → 0.2.4

package/src/browser.ts

@@ -9,6 +9,24 @@ export type { SupabaseClient } from "@supabase/supabase-js";
 export * from "./core.api";
 export * from "./core.interface";
 export * from "./core.utils";
+export type {
+    GetExtractionPayload,
+    PatchExtractionObjectsPayload,
+    PostExtractionPayload,
+    ScanExtractionListPayload,
+} from "./extraction/extraction.api";
+export {
+    getExtraction,
+    getExtractionSchema,
+    patchExtractionObjects,
+    patchExtractionObjectsSchema,
+    postExtraction,
+    postExtractionSchema,
+    scanExtractionList,
+    scanExtractionListSchema,
+} from "./extraction/extraction.api";
+export type { Extraction, ExtractionDetails } from "./extraction/extraction.interface";
+export { CategoryExtraction } from "./extraction/extraction.interface";
 export * from "./idea/idea.interface";
 export * from "./link/link.api";
 export * from "./link/link.interface";
@@ -86,32 +104,84 @@ export * from "./repo/repo.interface";
 export type {
     Api,
     ApiDetails,
-    DiscoverServiceInput,
+    ClaimRegistrySlotInput,
+    Config,
+    ConfigDetails,
     GetApiPayload,
+    GetConfigPayload,
     GetServicePayload,
+    PatchServiceRuntimeInput,
     PostApiPayload,
+    PostServiceInstanceOptions,
     PostServicePayload,
+    PostSystemRegistryConfigPayload,
+    RegisterServiceInput,
+    RegistrySlotGuardResult,
+    RegistrySlotRuntimeState,
+    ResetSystemRegistryConfigPayload,
     Service,
+    ServiceBootstrapResult,
     ServiceDetails,
+    ServiceNodeSnapshot,
+    ServiceRegistrySession,
+    ServiceRuntime,
+    ServiceSlot,
+    SystemRegistrySeedSlot,
+    TargetSystemRegistrySlotView,
+    TargetSystemRegistryView,
 } from "./service/index";
 export {
     ApiMethod,
     apiDetailsSchema,
+    assertRegistrySlotAvailable,
+    assertRegistrySlotOwner,
+    buildEmptyServiceSlots,
+    buildSystemRegistryConfigDetails,
+    CategoryConfig,
     CategoryService,
-    discoverService,
+    claimServiceRegistrySlot,
+    createActiveServiceLifecycle,
+    createClaimedRegistrySlotRuntimeState,
+    DEFAULT_SYSTEM_REGISTRY_SEED_SLOTS,
+    defaultL3ServiceDetails,
+    EMPTY_REGISTRY_SLOT_RUNTIME_STATE,
     fieldDefinitionSchema,
     getApi,
     getApiSchema,
+    getConfig,
+    getConfigSchema,
     getService,
     getServiceSchema,
+    getTargetSystemRegistry,
+    parseServiceSlot,
+    parseServiceSlots,
+    patchServiceRuntime,
     postApi,
     postApiSchema,
     postService,
+    postServiceInstance,
     postServiceSchema,
+    postSystemRegistryConfig,
+    postSystemRegistryConfigSchema,
+    registerService,
+    registerServiceAtStartup,
+    registrySlotRuntimePatchFromGuardResult,
+    resetSystemRegistryConfig,
+    resetSystemRegistryConfigSchema,
+    resolveActiveRegistryServiceId,
+    runRegistrySlotGuardCheck,
     ServiceLifecycleStatus,
+    ServiceRegistryError,
+    ServiceSlotStatus,
     schemaDefinitionSchema,
     serviceDetailsSchema,
     serviceLifecycleSchema,
+    serviceNodeSnapshotSchema,
+    serviceRuntimeSchema,
+    systemRegistrySeedSlotSchema,
+    TARGET_SYSTEM_REGISTRY_KEY,
+    unregisterService,
+    unregisterServiceAtShutdown,
 } from "./service/index";
 export type { FetchInitFactory, FetchRetryOptions } from "./shared/http/fetch-retry";
 export {
@@ -120,9 +190,31 @@ export {
     isRetryableHttpStatus,
     requestHasBody,
 } from "./shared/http/fetch-retry";
-export type { CreateLoggerInput, LoggerWithScope, LogScope, LogScopePatch } from "./shared/log";
-export { createLogger, LogLevel, logManager } from "./shared/log";
+export type {
+    CreateLoggerInput,
+    DecodedLogBatch,
+    FlatLogEntry,
+    LogEntry,
+    LoggerWithScope,
+    LogScope,
+    LogScopePatch,
+} from "./shared/log";
+export {
+    createLogger,
+    decodeLogBatch,
+    decodeLogBatchList,
+    flattenLogBatch,
+    flattenLogBatches,
+    isLogBatchList,
+    isLogEntry,
+    LOG_BATCH_LOADER_KEY,
+    LOG_PERSIST_LOADER_KEY,
+    LogLevel,
+    logManager,
+    parseLogBatchMeta,
+} from "./shared/log";
 export { isHttpUrl, resolveFetchUrl } from "./shared/utils/fetch-url";
+export { getValueAtPath } from "./shared/utils/get-value-at-path";
 export type {
     ClassifiedNetworkError,
     FormatNetworkErrorOptions,
@@ -160,6 +252,8 @@ export {
 } from "./task/task.interface";
 export type { PostTaskPayload } from "./task/task-post.api";
 export { postTask, postTaskSchema } from "./task/task-post.api";
+export type { PostTaskWithRetryOptions, PostTaskWithRetryResult } from "./task/task-post-retry.api";
+export { POST_TASK_DEFAULT_MAX_ATTEMPTS, postTaskWithRetry } from "./task/task-post-retry.api";
 export type { TaskStatusCount } from "./task/task-queue";
 export { countTasksByType, summarizeTaskQueue } from "./task/task-queue";
 export * from "./word/word.interface";

package/src/extraction/extraction.api.ts

@@ -0,0 +1,232 @@
+import { z } from "zod";
+import {
+    createTarget,
+    getPossibleTarget,
+    getTarget,
+    isCreateTargetAlreadyExistsError,
+    type QueryFilter,
+    scanTargetList,
+    updateTargetDetails,
+    validateWithSchema,
+} from "../core.api";
+import type { SupabaseResponse } from "../core.interface";
+import { generateResponse } from "../core.interface";
+import { createLogger } from "../shared/log";
+import { CategoryExtraction, type Extraction, type ExtractionDetails } from "./extraction.interface";
+
+const targetIdSchema = z.string().trim().min(1);
+const loaderKeySchema = z.string().trim().min(1);
+
+export const postExtractionSchema = z.object({
+    name: z.string().trim().min(1),
+    /** Source Target id — for log analysis this is the producing Task id. */
+    sourceId: targetIdSchema,
+    loaderKey: loaderKeySchema,
+    meta: z.unknown().optional(),
+    objects: z.array(z.unknown()).min(1),
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+
+export type PostExtractionPayload = z.infer<typeof postExtractionSchema>;
+
+export const getExtractionSchema = z
+    .object({
+        id: targetIdSchema.optional(),
+        sourceId: targetIdSchema.optional(),
+        loaderKey: loaderKeySchema.optional(),
+    })
+    .refine(
+        (payload) => {
+            const hasId = payload.id != null && payload.id !== "";
+            const hasSource = payload.sourceId != null && payload.sourceId !== "";
+            if (hasId) {
+                return !hasSource;
+            }
+            return hasSource && payload.loaderKey != null && payload.loaderKey !== "";
+        },
+        { message: "Provide id, or both sourceId and loaderKey" },
+    );
+
+export type GetExtractionPayload = z.infer<typeof getExtractionSchema>;
+
+export const scanExtractionListSchema = z.object({
+    loaderKey: loaderKeySchema.optional(),
+    sourceId: targetIdSchema.optional(),
+    maxRows: z.number().int().min(1).max(500).optional(),
+    ascending: z.boolean().optional(),
+});
+
+export type ScanExtractionListPayload = z.infer<typeof scanExtractionListSchema>;
+
+export const patchExtractionObjectsSchema = z.object({
+    id: targetIdSchema,
+    objects: z.array(z.unknown()).min(1),
+    meta: z.unknown().optional(),
+    expectedRevision: z.number().int().min(0).optional(),
+});
+
+export type PatchExtractionObjectsPayload = z.infer<typeof patchExtractionObjectsSchema>;
+
+const extractionCategoryFilter: QueryFilter = {
+    field: "category",
+    operator: "eq",
+    value: CategoryExtraction.EXTRACTION,
+};
+
+function extractionRedundancyFilters(sourceId: string, loaderKey: string): QueryFilter[] {
+    return [
+        extractionCategoryFilter,
+        { field: "value", operator: "eq", value: sourceId },
+        { field: "details->>loaderKey", operator: "eq", value: loaderKey },
+    ];
+}
+
+function normalizeExtractionMeta(meta: unknown, patch?: unknown): Record<string, unknown> {
+    const base =
+        meta != null && typeof meta === "object" && !Array.isArray(meta)
+            ? { ...(meta as Record<string, unknown>) }
+            : {};
+    if (patch != null && typeof patch === "object" && !Array.isArray(patch)) {
+        Object.assign(base, patch as Record<string, unknown>);
+    }
+    const revision = typeof base.revision === "number" && Number.isInteger(base.revision) ? base.revision : 0;
+    base.revision = revision;
+    base.updatedAt = new Date().toISOString();
+    return base;
+}
+
+/** Create an Extraction row for `(sourceId, loaderKey)`. Idempotent on redundancy key. */
+export const postExtraction = validateWithSchema(
+    postExtractionSchema,
+    "postExtractionSchema",
+)(async (payload): Promise<SupabaseResponse<Extraction>> => {
+    const logger = createLogger({ module: "postExtraction" });
+    const meta = normalizeExtractionMeta(payload.meta, { revision: 0 });
+
+    try {
+        return await createTarget<Extraction, PostExtractionPayload>({
+            payload,
+            checkRedundancyFilterList: extractionRedundancyFilters(payload.sourceId, payload.loaderKey),
+            createFn: () => ({
+                name: payload.name,
+                value: payload.sourceId,
+                category: CategoryExtraction.EXTRACTION,
+                tagList: payload.tagList,
+                extra: payload.extra,
+                details: {
+                    manifestVersion: 0,
+                    loaderKey: payload.loaderKey,
+                    meta,
+                    objects: payload.objects,
+                },
+            }),
+        });
+    } catch (error) {
+        if (isCreateTargetAlreadyExistsError(error)) {
+            logger.warn("Extraction already exists for source + loaderKey", {
+                topic: "extraction",
+                data: { sourceId: payload.sourceId, loaderKey: payload.loaderKey },
+            });
+            throw error;
+        }
+        throw error;
+    }
+});
+
+/** Fetch one Extraction by row id, or by `(sourceId, loaderKey)`. */
+export const getExtraction = validateWithSchema(
+    getExtractionSchema,
+    "getExtractionSchema",
+)(async (payload): Promise<SupabaseResponse<Extraction>> => {
+    if (payload.id != null && payload.id !== "") {
+        const result = await getTarget({
+            id: payload.id,
+            filterList: [extractionCategoryFilter],
+        });
+        return {
+            ...result,
+            data: result.data as Extraction | undefined,
+        };
+    }
+
+    const result = await getPossibleTarget({
+        filterList: extractionRedundancyFilters(payload.sourceId!, payload.loaderKey!),
+    });
+
+    if (result.data == null) {
+        return generateResponse.error("Extraction not found", undefined, "NOT_FOUND") as SupabaseResponse<Extraction>;
+    }
+
+    return {
+        ...result,
+        data: result.data as Extraction,
+    };
+});
+
+/** Scan Extraction rows (newest first by default). */
+export const scanExtractionList = validateWithSchema(
+    scanExtractionListSchema,
+    "scanExtractionListSchema",
+)(async (payload) => {
+    const filterList: QueryFilter[] = [extractionCategoryFilter];
+    if (payload.loaderKey != null) {
+        filterList.push({ field: "details->>loaderKey", operator: "eq", value: payload.loaderKey });
+    }
+    if (payload.sourceId != null) {
+        filterList.push({ field: "value", operator: "eq", value: payload.sourceId });
+    }
+
+    return scanTargetList<Extraction>({
+        category: CategoryExtraction.EXTRACTION,
+        filterList,
+        maxRows: payload.maxRows ?? 100,
+        orderBy: { field: "created_at", ascending: payload.ascending ?? false },
+    });
+});
+
+/** Replace {@link ExtractionDetails.objects} and bump `meta.revision`. */
+export const patchExtractionObjects = validateWithSchema(
+    patchExtractionObjectsSchema,
+    "patchExtractionObjectsSchema",
+)(async (payload): Promise<SupabaseResponse<Extraction>> => {
+    const optimisticLockFilterList: QueryFilter[] = [];
+    if (payload.expectedRevision != null) {
+        optimisticLockFilterList.push({
+            field: "details->meta->>revision",
+            operator: "eq",
+            value: String(payload.expectedRevision),
+        });
+    }
+
+    try {
+        const data = await updateTargetDetails<Extraction, ExtractionDetails>({
+            id: payload.id,
+            optimisticLockFilterList,
+            updateFn: (current) => {
+                const currentMeta =
+                    current.meta != null && typeof current.meta === "object" && !Array.isArray(current.meta)
+                        ? (current.meta as Record<string, unknown>)
+                        : {};
+                const revision =
+                    typeof currentMeta.revision === "number" && Number.isInteger(currentMeta.revision)
+                        ? currentMeta.revision + 1
+                        : 1;
+                return {
+                    ...current,
+                    meta: normalizeExtractionMeta(current.meta, {
+                        ...(payload.meta != null && typeof payload.meta === "object" && !Array.isArray(payload.meta)
+                            ? payload.meta
+                            : {}),
+                        revision,
+                    }),
+                    objects: payload.objects,
+                };
+            },
+        });
+        return generateResponse.success(data as Extraction);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message, undefined, "PATCH_FAILED") as SupabaseResponse<Extraction>;
+    }
+});

package/src/extraction/extraction.interface.ts

@@ -0,0 +1,45 @@
+import type { Target } from "../core.interface";
+
+/**
+ * Interpretation layer for a source Target: pipeline output (systems, models, algorithms)
+ * materialized as structured data. Not a process (see Task) or raw bytes (see Parcel).
+ *
+ * @see `.cursor/skills/extraction/SKILL.md`
+ */
+export interface Extraction extends Target {
+    /** Human-readable label. */
+    name: string;
+    /**
+     * Source Target id — the single input this row interprets (any category).
+     * Immutable after create. Indexed for lookup: all Extractions where `value = sourceId`.
+     * Not a dedup hash or pipeline run id.
+     */
+    value: string;
+    category: CategoryExtraction;
+    details: ExtractionDetails;
+}
+
+export enum CategoryExtraction {
+    EXTRACTION = "extraction",
+}
+
+export interface ExtractionDetails {
+    manifestVersion: 0;
+    /**
+     * Extractor identifier. Together with {@link Extraction.value} (source id) forms the
+     * logical unique key: one Extraction row per `(sourceTargetId, loaderKey)`.
+     * Determines how to parse and render {@link objects} (Extractor-owned schema).
+     */
+    loaderKey: string;
+    /**
+     * Extractor-owned metadata for this interpretation (e.g. revision, updatedAt, pipeline).
+     * Updated alongside {@link objects}; kept `unknown` at SDK boundary — see Extractor module.
+     */
+    meta: unknown;
+    /**
+     * Latest mutable analysis results for this source + Extractor — not an immutable snapshot.
+     * Shape is defined by the Extractor for {@link loaderKey}; SDK keeps `unknown[]` at core.
+     * Large payloads should reference Parcel (or similar) rather than inline in this array.
+     */
+    objects: Array<unknown>;
+}

package/src/list/list.interface.ts

@@ -13,8 +13,8 @@ export interface List extends Target {
 
 export interface ListDetails {
     manifestVersion: number;
-    /** If string, it is the meta brief of the list, TODO */
-    meta: string;
+    /** Optional list metadata (shape depends on `loaderKey`). */
+    meta: unknown;
     /** If string, it is the url of the preview TODO */
     preview: string;
     /** How to render the List */

package/src/node/node-runtime.base.ts

@@ -21,6 +21,16 @@ export interface NodeLoopContext {
     nodeId: string;
 }
 
+/** Shared options for {@link BaseNodeRuntime} and subclasses (e.g. TriggerNode). */
+export interface BaseNodeRuntimeOptions {
+    /**
+     * Called after node logout (or when the node was never registered),
+     * immediately before `process.exit`. Use for best-effort cleanup such as
+     * {@link unregisterServiceAtShutdown}. Errors are logged and ignored.
+     */
+    beforeProcessExit?: () => void | Promise<void>;
+}
+
 export const LOG_TOPIC_NODE = "node";
 const LOG_TOPIC_COMMAND = "command";
 const LOG_TOPIC_PROCESS = "process";
@@ -35,6 +45,7 @@ abstract class BaseNodeRuntime {
     private static readonly NODE_ID_PENDING_ASSIGNMENT = "pending-node-id";
 
     protected readonly runtimeModule: string;
+    private readonly beforeProcessExitHook: (() => void | Promise<void>) | null;
 
     private _localNodeId: string | null = null;
     private _isNodeIdLocked = false;
@@ -63,14 +74,34 @@ abstract class BaseNodeRuntime {
         this._isNodeIdLocked = true;
     }
 
-    protected constructor(runtimeModule: string) {
+    protected constructor(runtimeModule: string, options?: BaseNodeRuntimeOptions) {
         this.runtimeModule = runtimeModule;
+        this.beforeProcessExitHook = options?.beforeProcessExit ?? null;
         this.isRunning = false;
         this.loopCount = 0;
         this.startupTraceId = logManager.generateTraceId();
         this.startupScope = createScope({ module: runtimeModule, traceId: this.startupTraceId });
     }
 
+    private async runBeforeProcessExit(logger: LoggerWithScope): Promise<void> {
+        if (this.beforeProcessExitHook == null) {
+            return;
+        }
+        try {
+            await this.beforeProcessExitHook();
+        } catch (error) {
+            logger.warn("beforeProcessExit 钩子失败（best-effort）", {
+                topic: LOG_TOPIC_PROCESS,
+                data: { error: getErrorMessage(error) },
+            });
+        }
+    }
+
+    private async exitProcess(code: number, logger: LoggerWithScope): Promise<never> {
+        await this.runBeforeProcessExit(logger);
+        process.exit(code);
+    }
+
     /** Hook: task registration, trigger config load, etc. Throw to abort bootstrap. */
     protected abstract onBeforeRegisterNode(logger: LoggerWithScope): Promise<void>;
 
@@ -296,7 +327,7 @@ abstract class BaseNodeRuntime {
         }
 
         this.isRunning = false;
-        this.shutdownPromise = this.runShutdown(options?.trigger).catch((error) => {
+        this.shutdownPromise = this.runShutdown(options?.trigger).catch(async (error) => {
             const logger = createLogger({
                 scope: patchScope({ scope: this.startupScope, patch: { labels: { nodeId: this.getLogNodeId() } } }),
             });
@@ -307,7 +338,7 @@ abstract class BaseNodeRuntime {
                     error: getErrorMessage(error),
                 },
             });
-            process.exit(1);
+            await this.exitProcess(1, logger);
         });
         return this.shutdownPromise;
     }
@@ -324,7 +355,7 @@ abstract class BaseNodeRuntime {
 
         if (this.localNodeId == null) {
             logger.warn("本地節點未註冊，進程退出", { topic: LOG_TOPIC_NODE });
-            process.exit(0);
+            await this.exitProcess(0, logger);
             return;
         }
 
@@ -344,7 +375,7 @@ abstract class BaseNodeRuntime {
                 data: { error: getErrorMessage(error) },
             });
         } finally {
-            process.exit(0);
+            await this.exitProcess(0, logger);
         }
     }
 
@@ -391,7 +422,7 @@ abstract class BaseNodeRuntime {
         }
 
         this.consecutiveHeartbeatFailures = 0;
-        logger.success("心跳更新成功", {
+        logger.info("心跳更新成功", {
             topic: LOG_TOPIC_NODE,
             data: { lastHeartBeat: formatHeartbeat(lastHeartBeat) },
         });

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

@@ -0,0 +1,27 @@
+import { createLogger } from "../../shared/log/create-logger";
+import type { ManagedChildProcessesOptions } from "./managed-child-processes";
+import { ManagedChildProcesses } from "./managed-child-processes";
+
+export type CreateManagedChildProcessesOptions = Pick<
+    ManagedChildProcessesOptions,
+    "projectRoot" | "preloadModules" | "useTsx" | "graceMs"
+> & {
+    /** Defaults to `createLogger({ module: "launcher" })`. */
+    logger?: ManagedChildProcessesOptions["logger"];
+};
+
+const DEFAULT_PRELOAD_MODULES = ["./scripts/preload.mjs"] as const;
+
+/**
+ * Standard L3 service child-process registry: node (not tsx), service preload, launcher logger.
+ * Each service keeps a singleton in `src/startup/child-processes.ts`.
+ */
+export function createManagedChildProcesses(options: CreateManagedChildProcessesOptions): ManagedChildProcesses {
+    return new ManagedChildProcesses({
+        projectRoot: options.projectRoot,
+        preloadModules: options.preloadModules ?? DEFAULT_PRELOAD_MODULES,
+        useTsx: options.useTsx ?? false,
+        graceMs: options.graceMs,
+        logger: options.logger ?? createLogger({ module: "launcher" }),
+    });
+}

package/src/node/process/index.ts

@@ -1,5 +1,9 @@
+export type { CreateManagedChildProcessesOptions } from "./create-managed-child-processes";
+export { createManagedChildProcesses } from "./create-managed-child-processes";
 export type {
+    CriticalExitHandler,
     ManagedChildProcessesOptions,
+    SpawnChildOptions,
     SpawnChildResult,
     StopAllChildrenOptions,
 } from "./managed-child-processes";