target-supabase-sdk 0.1.9 → 0.2.1

package/src/parcel/parcel.api.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { createTarget, deleteTarget, getTarget, validateWithSchema } from "../core.api";
+import { CategoryParcel, type Parcel, type ParcelDetails } from "./parcel.interface";
+
+const parcelIdSchema = z.string().trim().min(1);
+
+const chunkSchema = z.object({
+    index: z.number().int().nonnegative(),
+    size: z.number().int().nonnegative(),
+    checksum: z.string().trim().min(1),
+    url: z.string().trim().min(1),
+    provider: z.string().optional(),
+});
+
+const parcelCryptoSchema = z.object({
+    enabled: z.boolean(),
+    algorithm: z.string().optional(),
+    iv: z.string().optional(),
+    keyDerivation: z.string().optional(),
+    salt: z.string().optional(),
+    pbkdf2Iterations: z.number().int().positive().optional(),
+});
+
+export const parcelDetailsSchema = z.object({
+    manifestVersion: z.number().int().nonnegative(),
+    chunkList: z.array(chunkSchema).min(1),
+    checksum: z.string().trim().min(1),
+    size: z.number().int().nonnegative(),
+    preview: z.string().optional(),
+    crypto: parcelCryptoSchema.optional(),
+});
+
+export const postParcelSchema = z.object({
+    name: z.string().trim().min(1),
+    value: z.string().trim().min(1),
+    details: parcelDetailsSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+
+export type PostParcelPayload = z.infer<typeof postParcelSchema>;
+
+export const getParcelSchema = z.object({
+    id: parcelIdSchema,
+});
+
+export type GetParcelPayload = z.infer<typeof getParcelSchema>;
+
+export const deleteParcelSchema = z.object({
+    id: parcelIdSchema,
+});
+
+export type DeleteParcelPayload = z.infer<typeof deleteParcelSchema>;
+
+const parcelCategoryFilter = {
+    field: "category",
+    operator: "eq" as const,
+    value: CategoryParcel.PARCEL,
+};
+
+/** Persist a Parcel row (`category=parcel`) after chunks are uploaded via {@link ParcelManager.save}. */
+export const postParcel = validateWithSchema(
+    postParcelSchema,
+    "postParcelSchema",
+)(async ({ name, value, details, tagList, extra }) => {
+    return createTarget<Parcel, PostParcelPayload>({
+        payload: { name, value, details, tagList, extra },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryParcel.PARCEL,
+            tagList,
+            extra,
+            details: details as ParcelDetails,
+        }),
+    });
+});
+
+/** Fetch a Parcel by id (`category=parcel`). */
+export const getParcel = validateWithSchema(
+    getParcelSchema,
+    "getParcelSchema",
+)(async ({ id }) => {
+    const result = await getTarget({
+        id,
+        filterList: [parcelCategoryFilter],
+    });
+    return {
+        ...result,
+        data: result.data as Parcel,
+    };
+});
+
+/** Delete a Parcel row by id (`category=parcel`). Does not remove chunk blobs from storage providers. */
+export const deleteParcel = validateWithSchema(
+    deleteParcelSchema,
+    "deleteParcelSchema",
+)(async ({ id }) => {
+    return deleteTarget({
+        id,
+        filterList: [parcelCategoryFilter],
+    });
+});

package/src/parcel/parcel.interface.ts

@@ -1,40 +1,61 @@
-import { Target } from "../core.interface";
+import type { Target } from "../core.interface";
+
+export enum CategoryParcel {
+    PARCEL = "parcel",
+}
 
 export interface Parcel extends Target {
-  category: CategoryParcel;
-  details: ParcelDetails;
+    /** Human readable name */
+    name: string;
+    /** Used to search the parcel, should be unique */
+    value: string;
+    category: CategoryParcel;
+    details: ParcelDetails;
 }
 
-export enum CategoryParcel {
-  PARCEL = "parcel",
+export interface ParcelCrypto {
+    /** 未設置或 false → 明文分片 */
+    enabled: boolean;
+    /** 例如 "AES-GCM-256"；enabled 時必填 */
+    algorithm?: string;
+    /** Base64 IV；AES-GCM 時必填 */
+    iv?: string;
+    /** 口令派生密鑰時的 KDF，例如 "PBKDF2-SHA256" */
+    keyDerivation?: string;
+    /** PBKDF2 salt（Base64）；keyDerivation 為 PBKDF2 時必填 */
+    salt?: string;
+    /** PBKDF2 迭代次數；未設置時由 SDK 默認 */
+    pbkdf2Iterations?: number;
 }
 
 export interface ParcelDetails {
-  manifestVersion: number;
-  chunkList: Chunk[];
-  /** sha256 */
-  checksum: string;
-  size: number;
+    manifestVersion: number;
+    chunkList: Chunk[];
+    /** 還原後的明文 sha256 */
+    checksum: string;
+    /** 還原後的明文大小（字節） */
+    size: number;
+    preview?: string;
+    crypto?: ParcelCrypto;
 }
 
 export enum LifecycleStatus {
-  STORED = "STORED",
-  SOFT_DELETED = "SOFT_DELETED",
-  HARD_DELETED = "HARD_DELETED",
+    STORED = "STORED",
+    SOFT_DELETED = "SOFT_DELETED",
+    HARD_DELETED = "HARD_DELETED",
 }
 
 export interface Lifecycle {
-  status: LifecycleStatus;
-  storedAt: string;
-  softDeletedAt: string | null;
-  hardDeletedAt: string | null;
+    status: LifecycleStatus;
+    storedAt: string;
+    softDeletedAt: string | null;
+    hardDeletedAt: string | null;
 }
 
 export interface Chunk {
-  index: number;
-  /** TODO Storage service provider */
-  // shardKey: string;
-  size: number;
-  checksum: string;
-  url: string;
+    index: number;
+    size: number;
+    checksum: string; // 該 chunk 字節的 sha256（明文或密文，與 create 時一致）
+    url: string;
+    provider?: string; // 對應 StorageAdapter / 平台標識（呼應 TODO shardKey）
 }

package/src/parcel/parcel.service.ts

@@ -0,0 +1,79 @@
+import type { SupabaseResponse } from "../core.interface";
+import { getParcel, postParcel } from "./parcel.api";
+import type { Parcel } from "./parcel.interface";
+import { type CreateOptions, ParcelManager, type ReassembleOptions, type StorageAdapter } from "./parcel-manager";
+
+export interface PublishParcelInput {
+    file: ArrayBuffer;
+    adapters: StorageAdapter[];
+    name: string;
+    value: string;
+    tagList?: string[];
+    extra?: string;
+    createOptions?: CreateOptions;
+}
+
+export interface PublishParcelResult {
+    parcel: Parcel;
+    /** Present when encrypted without passphrase — caller must persist outside Supabase */
+    key?: CryptoKey;
+}
+
+export interface RestoreParcelByIdInput {
+    id: string;
+    reassembleOptions?: ReassembleOptions;
+}
+
+export interface RestoreParcelByIdResult {
+    parcel: Parcel;
+    file: ArrayBuffer;
+}
+
+function requireResponseData<T>(response: SupabaseResponse<T>, label: string): T {
+    if (response.data == null) {
+        const suffix = response.message != null ? ` (${response.message})` : "";
+        throw new Error(`${label}: no data${suffix}`);
+    }
+    return response.data;
+}
+
+/**
+ * One-shot publish: split (optional encrypt) → upload chunks → persist Parcel row.
+ * Orchestrates {@link ParcelManager} + {@link postParcel}.
+ */
+export async function publishParcel(input: PublishParcelInput): Promise<PublishParcelResult> {
+    const { file, adapters, name, value, tagList = [], extra, createOptions } = input;
+
+    const createResult = await ParcelManager.create(file, createOptions ?? {});
+    const draft = await ParcelManager.save(createResult, adapters, { name, value, tagList });
+
+    const response = await postParcel({
+        name: draft.name,
+        value: draft.value,
+        details: draft.details,
+        tagList: draft.tagList ?? [],
+        extra,
+    });
+
+    return {
+        parcel: requireResponseData(response, "postParcel"),
+        key: createResult.key,
+    };
+}
+
+/**
+ * Reassemble file bytes from a {@link Parcel} (chunk URLs in details).
+ */
+export async function restoreParcel(parcel: Parcel, reassembleOptions?: ReassembleOptions): Promise<ArrayBuffer> {
+    return ParcelManager.reassemble(parcel, reassembleOptions ?? {});
+}
+
+/**
+ * Fetch Parcel by id, then reassemble. Orchestrates {@link getParcel} + {@link restoreParcel}.
+ */
+export async function restoreParcelById(input: RestoreParcelByIdInput): Promise<RestoreParcelByIdResult> {
+    const response = await getParcel({ id: input.id });
+    const parcel = requireResponseData(response, "getParcel");
+    const file = await restoreParcel(parcel, input.reassembleOptions);
+    return { parcel, file };
+}

package/src/parcel/storage-provider-registry.ts

@@ -0,0 +1,49 @@
+import { registerProviderChunkResolver } from "./chunk-fetch-registry";
+import type { ProviderProbeResult, StorageProviderModule } from "./storage-provider.types";
+
+export type ProviderProbeMap = Record<string, ProviderProbeResult | { ok: true; detail: { skipped: true } }>;
+
+export interface StorageProviderRegistry {
+    register(module: StorageProviderModule): void;
+    get(provider: string): StorageProviderModule;
+    has(provider: string): boolean;
+    list(): string[];
+    probeAll(): Promise<ProviderProbeMap>;
+}
+
+/** In-process registry for {@link StorageProviderModule}; syncs chunk resolvers on register. */
+export function createStorageProviderRegistry(): StorageProviderRegistry {
+    const modules = new Map<string, StorageProviderModule>();
+
+    return {
+        register(module) {
+            modules.set(module.provider, module);
+            registerProviderChunkResolver(module);
+        },
+        get(provider) {
+            const found = modules.get(provider);
+            if (found == null) {
+                const available = [...modules.keys()].join(", ") || "(none)";
+                throw new Error(`Unknown storage provider: ${provider}. Registered: ${available}`);
+            }
+            return found;
+        },
+        has(provider) {
+            return modules.has(provider);
+        },
+        list() {
+            return [...modules.keys()];
+        },
+        async probeAll() {
+            const out: ProviderProbeMap = {};
+            for (const [name, module] of modules) {
+                if (module.probe == null) {
+                    out[name] = { ok: true, detail: { skipped: true } };
+                    continue;
+                }
+                out[name] = await module.probe();
+            }
+            return out;
+        },
+    };
+}

package/src/parcel/storage-provider.types.ts

@@ -0,0 +1,45 @@
+import type { ChunkResolveProvider } from "./chunk-fetch-registry";
+import type { Parcel } from "./parcel.interface";
+import type { StorageAdapter } from "./parcel-manager";
+
+export interface ProviderProbeOk {
+    ok: true;
+    detail?: Record<string, unknown>;
+}
+
+export interface ProviderProbeFail {
+    ok: false;
+    error: string;
+}
+
+export type ProviderProbeResult = ProviderProbeOk | ProviderProbeFail;
+
+/** Best-effort rollback of partial uploads. */
+export interface UploadTracker<THandle> {
+    readonly handles: THandle[];
+    push(handle: THandle): void;
+}
+
+export interface CreateUploadAdapterOptions {
+    /** Collect rollback handles during upload (partial-failure cleanup). */
+    tracker?: UploadTracker<unknown>;
+}
+
+/** Full storage backend module: upload, restore, probe, rollback. */
+export interface StorageProviderModule extends ChunkResolveProvider {
+    createUploadAdapter(options?: CreateUploadAdapterOptions): StorageAdapter;
+    probe?(): Promise<ProviderProbeResult>;
+    rollbackUpload?(handles: unknown[]): Promise<void>;
+    /** Validate parcel before restore (provider mix, missing chunks). */
+    assertParcelRestorable?(parcel: Parcel): void;
+}
+
+export function createUploadTracker<THandle>(): UploadTracker<THandle> {
+    const handles: THandle[] = [];
+    return {
+        handles,
+        push(handle: THandle) {
+            handles.push(handle);
+        },
+    };
+}

package/src/preload.ts

@@ -0,0 +1,7 @@
+/**
+ * Node `--import` entry — `target-supabase-sdk/preload`
+ * @see .cursor/skills/service-preload/SKILL.md
+ */
+
+export { runServicePreload } from "./node/preload/run-service-preload";
+export type { ServicePreloadOptions } from "./node/preload/service-preload.interface";

package/src/repo/repo-context.utils.ts

@@ -31,15 +31,14 @@ export function isTaskRepoContext(value: unknown): value is TaskRepoContext {
 export function normalizeRepoContextModule(
     moduleExports: unknown,
     taskTypeKey: string,
-    exportName?: string
+    exportName?: string,
 ): TaskRepoContext | null {
     if (moduleExports == null) {
         return null;
     }
 
     const record = moduleExports as Record<string, unknown>;
-    const namedExport =
-        exportName != null && exportName !== "" ? record[exportName] : undefined;
+    const namedExport = exportName != null && exportName !== "" ? record[exportName] : undefined;
     const defaultExport = record.default;
     const candidate = namedExport ?? defaultExport ?? moduleExports;
 
@@ -103,7 +102,7 @@ export function getScriptLoadKey(script: TaskRepoScriptRecord): string {
 }
 
 export function assertScriptLoadable(
-    details: TaskRepoScriptDetails
+    details: TaskRepoScriptDetails,
 ): details is TaskRepoScriptDetails & ({ source: string } | { modulePath: string }) {
     const hasSource = details.source != null && details.source.trim() !== "";
     const hasModulePath = details.modulePath != null && details.modulePath.trim() !== "";

package/src/repo/repo-manager.ts

@@ -1,21 +1,11 @@
-import { getPossibleTarget } from "../core.api";
-import { SupabaseInitializer } from "../supabase";
-import { LoggerWithContext } from "../shared/log/log-manager";
+import { getPossibleTarget } from "../core.api";
+import type { LoggerWithScope } from "../shared/log";
+import { supabase } from "../supabase";
 import type { TaskRepoContext, TaskRepoScriptRecord } from "../task/task-repo-context";
 import { TASK_REPO_SCRIPT_CATEGORY } from "../task/task-repo-context";
-import {
-    assertScriptLoadable,
-    isTaskRepoContext,
-    pickEntryScript,
-} from "./repo-context.utils";
-import { CategoryRepo, Repo } from "./repo.interface";
-import {
-    clearRepoScriptModuleCache,
-    loadRepoContextFromScript,
-    loadRepoContextFromUrl,
-} from "./repo.script-loader";
-
-const supabase = SupabaseInitializer.getInstance();
+import { CategoryRepo, type Repo } from "./repo.interface";
+import { clearRepoScriptModuleCache, loadRepoContextFromScript, loadRepoContextFromUrl } from "./repo.script-loader";
+import { assertScriptLoadable, isTaskRepoContext, pickEntryScript } from "./repo-context.utils";
 
 type LocalRepoEntry =
     | { kind: "context"; context: TaskRepoContext }
@@ -24,16 +14,31 @@ type LocalRepoEntry =
 const localRepoRegistry = new Map<string, LocalRepoEntry>();
 const remoteContextCache = new Map<string, TaskRepoContext>();
 
+export type RepoContextFailureReason =
+    | "LOCAL_REPO_LOAD_FAILED"
+    | "LOCAL_REPO_NOT_FOUND"
+    | "REMOTE_REPO_NOT_FOUND"
+    | "REMOTE_REPO_LOAD_FAILED";
+
+export type RepoContextResolvedVia = "local" | "remote";
+
 export interface GetRepoContextParams {
-    logger: LoggerWithContext;
+    logger: LoggerWithScope;
     /** Task type key (`task.value`) — matches {@link Repo.value} for remote lookup; local registry key */
     taskTypeKey: string;
+    /**
+     * When false, skip Supabase fetch if the task type is not in the local registry.
+     * Default `true`.
+     */
+    includeRemote?: boolean;
 }
 
 export interface GetRepoContextResult<T extends TaskRepoContext = TaskRepoContext> {
     context: T | null;
     /** Present when `context` is null — import / DB / format failure at repo layer */
     error?: string;
+    failureReason?: RepoContextFailureReason;
+    resolvedVia?: RepoContextResolvedVia;
 }
 
 function buildRemoteCacheKey(taskTypeKey: string, contentHash: string): string {
@@ -65,9 +70,9 @@ async function fetchRemoteScripts(taskTypeKey: string): Promise<TaskRepoScriptRe
 }
 
 async function loadLocalEntry(
-    logger: LoggerWithContext,
+    logger: LoggerWithScope,
     entry: LocalRepoEntry,
-    taskTypeKey: string
+    taskTypeKey: string,
 ): Promise<TaskRepoContext | null> {
     if (entry.kind === "context") {
         return entry.context;
@@ -90,17 +95,14 @@ async function loadLocalEntry(
     return loaded?.context ?? null;
 }
 
-async function loadRemoteRepoContext(
-    logger: LoggerWithContext,
-    taskTypeKey: string
-): Promise<GetRepoContextResult> {
-    logger.info("從 Supabase 加載 Repo", { topic: "repo", context: { taskTypeKey } });
+async function loadRemoteRepoContext(logger: LoggerWithScope, taskTypeKey: string): Promise<GetRepoContextResult> {
+    logger.info("從 Supabase 加載 Repo", { topic: "repo", data: { taskTypeKey } });
 
     const remoteRepo = await fetchRemoteRepo(taskTypeKey);
     if (remoteRepo == null) {
         const error = `Supabase 未找到 Repo (value=${taskTypeKey})`;
-        logger.warn(error, { topic: "repo", context: { taskTypeKey } });
-        return { context: null, error };
+        logger.warn(error, { topic: "repo", data: { taskTypeKey } });
+        return { context: null, error, failureReason: "REMOTE_REPO_NOT_FOUND" };
     }
 
     const repoUrl = remoteRepo.details?.url?.trim() ?? "";
@@ -108,8 +110,8 @@ async function loadRemoteRepoContext(
     const cacheKey = buildRemoteCacheKey(taskTypeKey, repoHash);
     const cached = remoteContextCache.get(cacheKey);
     if (cached != null) {
-        logger.info("命中遠程 Repo 上下文緩存", { topic: "repo", context: { cacheKey } });
-        return { context: cached };
+        logger.info("命中遠程 Repo 上下文緩存", { topic: "repo", data: { cacheKey } });
+        return { context: cached, resolvedVia: "remote" };
     }
 
     const scripts = await fetchRemoteScripts(taskTypeKey);
@@ -123,7 +125,7 @@ async function loadRemoteRepoContext(
     if (loaded == null && repoUrl !== "") {
         logger.info("未找到 script 行，嘗試從 Repo.details.url 加載", {
             topic: "repo",
-            context: { taskTypeKey, url: repoUrl },
+            data: { taskTypeKey, url: repoUrl },
         });
         loaded = await loadRepoContextFromUrl({ logger, url: repoUrl, taskTypeKey });
     }
@@ -132,47 +134,55 @@ async function loadRemoteRepoContext(
         const error = `無法從 Repo 加載 TaskRepoContext (hasUrl=${repoUrl !== ""}, scriptCount=${scripts.length})`;
         logger.warn(error, {
             topic: "repo",
-            context: { taskTypeKey, hasUrl: repoUrl !== "", scriptCount: scripts.length },
+            data: { taskTypeKey, hasUrl: repoUrl !== "", scriptCount: scripts.length },
         });
-        return { context: null, error };
+        return { context: null, error, failureReason: "REMOTE_REPO_LOAD_FAILED" };
     }
 
     remoteContextCache.set(cacheKey, loaded.context);
-    return { context: loaded.context };
+    return { context: loaded.context, resolvedVia: "remote" };
 }
 
 const getRepoContext = async <RepoContext extends TaskRepoContext>({
     logger,
     taskTypeKey,
+    includeRemote = true,
 }: GetRepoContextParams): Promise<GetRepoContextResult<RepoContext>> => {
     const localEntry = localRepoRegistry.get(taskTypeKey);
     if (localEntry != null) {
-        logger.info("使用本地註冊的 Repo", { topic: "repo", context: { taskTypeKey } });
+        logger.info("使用本地註冊的 Repo", { topic: "repo", data: { taskTypeKey } });
         const context = await loadLocalEntry(logger, localEntry, taskTypeKey);
         if (context != null && isTaskRepoContext(context)) {
-            return { context: context as RepoContext };
+            return { context: context as RepoContext, resolvedVia: "local" };
         }
         const error = "本地 Repo 模組加載失敗或未導出有效的 TaskRepoContext";
-        logger.warn(error, { topic: "repo", context: { taskTypeKey } });
-        return { context: null, error };
+        logger.warn(error, { topic: "repo", data: { taskTypeKey } });
+        return { context: null, error, failureReason: "LOCAL_REPO_LOAD_FAILED" };
+    }
+
+    if (!includeRemote) {
+        const error = `本地未註冊 Repo (value=${taskTypeKey})`;
+        logger.warn(error, { topic: "repo", data: { taskTypeKey, includeRemote: false } });
+        return { context: null, error, failureReason: "LOCAL_REPO_NOT_FOUND" };
     }
 
     try {
         const result = await loadRemoteRepoContext(logger, taskTypeKey);
         if (result.context != null && isTaskRepoContext(result.context)) {
-            return { context: result.context as RepoContext };
+            return { context: result.context as RepoContext, resolvedVia: "remote" };
         }
         return {
             context: null,
             error: result.error ?? "遠程 Repo 上下文無效",
+            failureReason: result.failureReason ?? "REMOTE_REPO_LOAD_FAILED",
         };
     } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         logger.error("從 Supabase 加載 Repo 失敗", {
             topic: "repo",
-            context: { taskTypeKey, error: message },
+            data: { taskTypeKey, error: message },
         });
-        return { context: null, error: message };
+        return { context: null, error: message, failureReason: "REMOTE_REPO_LOAD_FAILED" };
     }
 };
 
@@ -196,6 +206,10 @@ function unregisterLocalRepo(taskTypeKey: string): void {
     localRepoRegistry.delete(taskTypeKey);
 }
 
+function hasLocalRepo(taskTypeKey: string): boolean {
+    return localRepoRegistry.has(taskTypeKey);
+}
+
 function getRegisteredLocalTaskTypeKeys(): string[] {
     return [...localRepoRegistry.keys()];
 }
@@ -209,6 +223,7 @@ const RepoManager = {
     registerLocalRepoContext,
     registerLocalModule,
     unregisterLocalRepo,
+    hasLocalRepo,
     getRegisteredLocalTaskTypeKeys,
     clearRemoteContextCache,
     clearRepoScriptModuleCache,

package/src/repo/repo.api.ts

@@ -1,7 +1,7 @@
-import { scanTargetList, validateWithSchema } from "../core.api";
-import { generateResponse, SupabaseResponse } from "../core.interface";
 import { z } from "zod";
-import { CategoryRepo, Repo } from "./repo.interface";
+import { scanTargetList, validateWithSchema } from "../core.api";
+import { generateResponse, type SupabaseResponse } from "../core.interface";
+import { CategoryRepo, type Repo } from "./repo.interface";
 
 const REPO_USAGE_FIELD = "details->>usage" as const;
 
@@ -16,7 +16,7 @@ export type GetScanRemoteRepoValuesPayload = z.infer<typeof getScanRemoteRepoVal
  * Returns `{ data: string[] }` on success; validation and DB failures use `{ error }` (never throws).
  */
 export const getScanRemoteRepoValues = async (
-    payload: GetScanRemoteRepoValuesPayload
+    payload: GetScanRemoteRepoValuesPayload,
 ): Promise<SupabaseResponse<string[]>> => {
     try {
         return await getScanRemoteRepoValuesValidated(payload);
@@ -28,7 +28,7 @@ export const getScanRemoteRepoValues = async (
 
 const getScanRemoteRepoValuesValidated = validateWithSchema(
     getScanRemoteRepoValuesSchema,
-    "getScanRemoteRepoValuesSchema"
+    "getScanRemoteRepoValuesSchema",
 )(async ({ usage }): Promise<SupabaseResponse<string[]>> => {
     try {
         const { data } = await scanTargetList<Repo>({

package/src/repo/repo.interface.ts

@@ -1,4 +1,4 @@
-import { Target } from "../core.interface";
+import type { Target } from "../core.interface";
 
 export enum CategoryRepo {
     /** Project */
@@ -28,4 +28,3 @@ export interface RepoDetails {
     url: string;
     hash: string;
 }
-