target-supabase-sdk 0.2.0 → 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 { LoggerWithScope } from "../shared/log";
+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 }
@@ -82,7 +72,7 @@ async function fetchRemoteScripts(taskTypeKey: string): Promise<TaskRepoScriptRe
 async function loadLocalEntry(
     logger: LoggerWithScope,
     entry: LocalRepoEntry,
-    taskTypeKey: string
+    taskTypeKey: string,
 ): Promise<TaskRepoContext | null> {
     if (entry.kind === "context") {
         return entry.context;
@@ -105,10 +95,7 @@ async function loadLocalEntry(
     return loaded?.context ?? null;
 }
 
-async function loadRemoteRepoContext(
-    logger: LoggerWithScope,
-    taskTypeKey: string
-): Promise<GetRepoContextResult> {
+async function loadRemoteRepoContext(logger: LoggerWithScope, taskTypeKey: string): Promise<GetRepoContextResult> {
     logger.info("從 Supabase 加載 Repo", { topic: "repo", data: { taskTypeKey } });
 
     const remoteRepo = await fetchRemoteRepo(taskTypeKey);

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;
 }
-

package/src/repo/repo.script-loader.ts

@@ -1,16 +1,12 @@
 import { createHash } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
 
-import { LoggerWithScope } from "../shared/log";
+import type { LoggerWithScope } from "../shared/log";
 import { resolvePathFromCwd, toFileImportHref } from "../shared/utils/config-path.utils";
-import { TaskRepoScriptRecord } from "../task/task-repo-context";
-import {
-    getScriptLoadKey,
-    LoadedRepoContext,
-    normalizeRepoContextModule,
-} from "./repo-context.utils";
+import type { TaskRepoScriptRecord } from "../task/task-repo-context";
+import { getScriptLoadKey, type LoadedRepoContext, normalizeRepoContextModule } from "./repo-context.utils";
 
 const importedModuleCache = new Map<string, LoadedRepoContext>();
 

package/src/service/base.interface.ts

@@ -1,97 +1,88 @@
-import { Target } from "../core.interface";
-
-export enum LifecycleStatus {
-  ACTIVE = "ACTIVE",
-  DEPRECATED = "DEPRECATED",
-  SUNSET = "SUNSET",
-}
-
-export interface Lifecycle {
-  status: LifecycleStatus;
-  /** YYYY-MM-DD */
-  activeSince: string;
-  deprecatedAt: string | null;
-  sunsetAt: string | null;
+export enum ServiceLifecycleStatus {
+    ACTIVE = "ACTIVE",
+    DEPRECATED = "DEPRECATED",
+    SUNSET = "SUNSET",
 }
 
-export type Field =
-  | {
-    type: "string";
-    nullable: boolean;
-    required: boolean;
-    /** 1 */
-    minLength: number;
-    /** 64 */
-    maxLength: number;
-    /** ^[a-z0-9_-]+$ */
-    pattern: string;
-  }
-  | {
-    type: "number";
-    nullable: boolean;
-    required: boolean;
-    /** 1 */
-    minimum: number;
-    /** 64 */
-    maximum: number;
-  }
-  | {
-    type: "boolean";
-    nullable: boolean;
-    required: boolean;
-  }
-  | {
-    type: "enum";
-    nullable: boolean;
-    required: boolean;
-    /** 'core.Gender.0' */
-    enumKey: string;
-  }
-  | {
-    type: "array";
-    nullable: boolean;
-    required: boolean;
-    /** 'string'|'number'|'boolean'|'enum.enumKey'|'ref.refKey' */
-    itemType: string;
-  }
-  | {
-    /** Object */
-    type: "ref";
-    nullable: boolean;
-    required: boolean;
-    /** 'core.QuestionReview.0' */
-    refKey: string;
-  };
-
-
-export interface TargetDescriptor extends Target {
-  /** "core.QuestionReview.0" 唯一键 领域 + targetName + VERSION */
-  value: string;
-  category: 'target-descriptor';
-  details: TargetDescriptorDetails;
+export interface ServiceLifecycle {
+    status: ServiceLifecycleStatus;
+    /** YYYY-MM-DD */
+    activeSince: string;
+    deprecatedAt: string | null;
+    sunsetAt: string | null;
 }
 
-export interface TargetDescriptorDetails {
-  list: Array<{
-    name: string;
-  } & Field>;
-  refMap?: Record<string, TargetDescriptor>;
-  enumMap?: Record<string, string[]>;
-  manifestVersion: number;
-}
-
-export interface EnumDescriptor extends Target {
-  /** "core.Gender.0" 唯一键 领域 + enumName + VERSION */
-  value: string;
-  category: 'target-descriptor';
-  details: EnumDescriptorDetails;
-}
-
-export interface EnumDescriptorDetails {
-  list: Array<{
+/** Inline enum members (no registry lookup). */
+export type EnumMembers = ReadonlyArray<{
     key: string;
     value: string;
-  }>;
-  manifestVersion: number;
-}
+}>;
+
+/**
+ * Schema node without a field name — used for array items and anonymous nesting.
+ * Named properties use {@link FieldDefinition} (`fieldName` + `SchemaDefinition`).
+ */
+export type SchemaDefinition =
+    | {
+          type: "string";
+          nullable: boolean;
+          optional: boolean;
+          /** string length */
+          min?: number;
+          /** string length */
+          max?: number;
+          /** e.g. ^[a-z0-9_-]+$ */
+          regex?: string;
+          default?: string;
+      }
+    | {
+          type: "number";
+          nullable: boolean;
+          optional: boolean;
+          min?: number;
+          max?: number;
+          default?: number;
+      }
+    | {
+          type: "boolean";
+          nullable: boolean;
+          optional: boolean;
+          default?: boolean;
+      }
+    | {
+          type: "unknown";
+          nullable: boolean;
+          optional: boolean;
+          default?: unknown;
+      }
+    | {
+          type: "enum";
+          nullable: boolean;
+          optional: boolean;
+          members: EnumMembers;
+          /** Must match a `members[].key` */
+          defaultKey?: string;
+      }
+    | {
+          type: "object";
+          nullable: boolean;
+          optional: boolean;
+          fields: FieldDefinition[];
+          default?: Record<string, unknown>;
+      }
+    | {
+          type: "array";
+          nullable: boolean;
+          optional: boolean;
+          items: SchemaDefinition;
+          /** min/max item count */
+          min?: number;
+          max?: number;
+          default?: unknown;
+      };
 
+/**
+ * Named field schema. `fieldName` is required for introspection (walk paths, docs, forms).
+ * Use `fields: FieldDefinition[]` — not `Record<string, …>` — so the name has a single source of truth.
+ */
+export type FieldDefinition = { fieldName: string } & SchemaDefinition;