target-supabase-sdk 0.2.15 → 0.2.17

package/src/service/{registry.service.ts → registry/registry.service.ts}

@@ -9,21 +9,17 @@
  *     for crashed / ungraceful exits (stale `Service.details.runtime`)
  */
 
-import { isOptimisticLockError, updateTargetDetails } from "../core.api";
-import type { Node } from "../node/node.interface";
-import { createLogger } from "../shared/log";
-import { getConfig } from "./config.api";
-import { type Config, type ConfigDetails, TARGET_SYSTEM_REGISTRY_KEY } from "./config.interface";
-import { getService } from "./service.api";
-import {
-    type Service,
-    type ServiceDetails,
-    type ServiceNodeSnapshot,
-    type ServiceSlot,
-    ServiceSlotStatus,
-} from "./service.interface";
-
-export { TARGET_SYSTEM_REGISTRY_KEY } from "./config.interface";
+import { getConfig } from "../../config/config.api";
+import type { Config, ConfigDetails } from "../../config/config.interface";
+import { isOptimisticLockError, updateTargetDetails } from "../../core.api";
+import type { Node } from "../../node/node.interface";
+import { createLogger } from "../../shared/log";
+import { getService } from "../service.api";
+import type { Service, ServiceDetails, ServiceNodeSnapshot } from "../service.interface";
+import { TARGET_SYSTEM_REGISTRY_KEY } from "./registry.constant";
+import { type ServiceSlot, ServiceSlotStatus } from "./registry.interface";
+
+export { TARGET_SYSTEM_REGISTRY_KEY } from "./registry.constant";
 
 /** `details.meta.revision` on the system registry Config — optimistic-lock token. */
 interface RegistryConfigMeta {
@@ -85,19 +81,24 @@ export interface ReleaseSystemRegistrySlotsByServiceIdOutcome {
     unchangedServiceIds: string[];
 }
 
-export interface AppendSystemRegistrySlotsInput {
-    /** Logical service keys to declare with one new EMPTY slot each when missing. */
-    serviceValues: string[];
+export interface AppendSystemRegistryEmptySlotsInput {
+    /** Logical service key (e.g. `download-service`). */
+    serviceValue: string;
+    /** How many EMPTY slots to append. Default `1`. */
+    count?: number;
     traceId?: string;
     maxAttempts?: number;
 }
 
-export interface AppendSystemRegistrySlotsOutcome {
+export interface AppendSystemRegistryEmptySlotsOutcome {
     config: Config;
-    /** Service keys that received a new EMPTY slot this run. */
-    added: string[];
-    /** Requested keys that already had at least one declared slot — no change. */
-    skipped: string[];
+    serviceValue: string;
+    /** EMPTY slots appended this run. */
+    appended: number;
+    /** Declared slot count for `serviceValue` before this run. */
+    capacityBefore: number;
+    /** Declared slot count for `serviceValue` after this run. */
+    capacityAfter: number;
 }
 
 export class ServiceRegistryError extends Error {
@@ -618,30 +619,35 @@ export async function releaseSystemRegistrySlotsByServiceId(
 }
 
 /**
- * Append EMPTY {@link ServiceSlot} rows for logical service keys not yet declared.
- * Idempotent — skips keys that already appear in `details.objects`.
+ * Append one or more EMPTY {@link ServiceSlot} rows for a given `serviceValue`.
+ *
+ * Always grows capacity (does not skip when the key is already declared).
+ * Use for replica scale-out (e.g. second `download-service` instance).
  * Does not modify existing slots or release ACTIVE bindings.
  */
-export async function appendSystemRegistrySlots(
-    input: AppendSystemRegistrySlotsInput,
-): Promise<AppendSystemRegistrySlotsOutcome> {
-    const serviceValues = [
-        ...new Set(input.serviceValues.map((value) => value.trim()).filter((value) => value !== "")),
-    ];
-    if (serviceValues.length === 0) {
-        throw new Error("[appendSystemRegistrySlots] serviceValues must not be empty");
+export async function appendSystemRegistryEmptySlots(
+    input: AppendSystemRegistryEmptySlotsInput,
+): Promise<AppendSystemRegistryEmptySlotsOutcome> {
+    const serviceValue = input.serviceValue.trim();
+    if (serviceValue === "") {
+        throw new Error("[appendSystemRegistryEmptySlots] serviceValue must not be empty");
+    }
+
+    const count = input.count ?? 1;
+    if (!Number.isInteger(count) || count < 1) {
+        throw new Error("[appendSystemRegistryEmptySlots] count must be an integer >= 1");
     }
 
     const maxAttempts = input.maxAttempts ?? DEFAULT_REGISTER_RETRY_ATTEMPTS;
     const logger = createLogger({
-        module: "appendSystemRegistrySlots",
+        module: "appendSystemRegistryEmptySlots",
         traceId: input.traceId,
-        labels: { serviceValues: serviceValues.join(",") },
+        labels: { serviceValue, count: String(count) },
     });
 
-    logger.info("开始追加 registry 槽位声明", {
+    logger.info("开始追加 EMPTY registry 槽位", {
         topic: LOG_TOPIC_REGISTRY,
-        data: { serviceValues },
+        data: { serviceValue, count },
     });
 
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
@@ -649,31 +655,16 @@ export async function appendSystemRegistrySlots(
             const config = await loadSystemRegistryConfig();
             const revision = parseRegistryRevision(config.details.meta);
             const slots = parseServiceSlots(config);
+            const capacityBefore = slots.filter((slot) => slot.serviceValue === serviceValue).length;
 
-            const added: string[] = [];
-            const skipped: string[] = [];
-            const nextSlots = [...slots];
-
-            for (const serviceValue of serviceValues) {
-                if (isServiceValueDeclared(nextSlots, serviceValue)) {
-                    skipped.push(serviceValue);
-                    continue;
-                }
-                nextSlots.push({
+            const nextSlots = [
+                ...slots,
+                ...Array.from({ length: count }, () => ({
                     serviceValue,
                     serviceId: null,
                     status: ServiceSlotStatus.EMPTY,
-                });
-                added.push(serviceValue);
-            }
-
-            if (added.length === 0) {
-                logger.info("所有 service 已声明 — 无需追加", {
-                    topic: LOG_TOPIC_REGISTRY,
-                    data: { serviceValues, skipped },
-                });
-                return { config, added, skipped: serviceValues };
-            }
+                })),
+            ];
 
             await persistSlotClaim({
                 configId: config.id,
@@ -682,33 +673,43 @@ export async function appendSystemRegistrySlots(
             });
 
             const updated = await loadSystemRegistryConfig();
-            logger.info("registry 槽位追加成功", {
+            const capacityAfter = parseServiceSlots(updated).filter(
+                (slot) => slot.serviceValue === serviceValue,
+            ).length;
+
+            logger.info("EMPTY registry 槽位追加成功", {
                 topic: LOG_TOPIC_REGISTRY,
-                data: { added, skipped, attempt, revision: revision + 1 },
+                data: { serviceValue, appended: count, capacityBefore, capacityAfter, attempt },
             });
 
-            return { config: updated, added, skipped };
+            return {
+                config: updated,
+                serviceValue,
+                appended: count,
+                capacityBefore,
+                capacityAfter,
+            };
         } catch (error) {
             if (isOptimisticLockError(error) && attempt < maxAttempts) {
                 logger.warn("registry 乐观锁冲突，重试", {
                     topic: LOG_TOPIC_REGISTRY,
-                    data: { serviceValues, attempt, maxAttempts },
+                    data: { serviceValue, count, attempt, maxAttempts },
                 });
                 await sleep(50 * attempt);
                 continue;
             }
 
             const message = error instanceof Error ? error.message : String(error);
-            logger.error("registry 槽位追加失败", {
+            logger.error("EMPTY registry 槽位追加失败", {
                 topic: LOG_TOPIC_REGISTRY,
-                data: { serviceValues, attempt, message },
+                data: { serviceValue, count, attempt, message },
             });
             throw new ServiceRegistryError(message, "REGISTRY_UPDATE_FAILED");
         }
     }
 
     throw new ServiceRegistryError(
-        "[appendSystemRegistrySlots] Optimistic lock retries exhausted",
+        "[appendSystemRegistryEmptySlots] Optimistic lock retries exhausted",
         "REGISTRY_UPDATE_FAILED",
     );
 }

package/src/service/service.interface.ts

@@ -45,18 +45,6 @@ export interface ServiceRuntime {
     nodes: ServiceNodeSnapshot[];
 }
 
-export enum ServiceSlotStatus {
-    EMPTY = "EMPTY",
-    ACTIVE = "ACTIVE",
-}
-
-export interface ServiceSlot {
-    serviceValue: string;
-    /** Bound {@link Service.id} when {@link ServiceSlotStatus.ACTIVE}; null when EMPTY. */
-    serviceId: string | null;
-    status: ServiceSlotStatus;
-}
-
 export interface Api extends Target {
     /** "core.post.target.0" 唯一键 领域 + METHOD + content + VERSION */
     value: string;

package/src/shared/media/README.md

@@ -0,0 +1,109 @@
+# Media Links (`shared/media`)
+
+Media is a **convention on `Link`**, not a new Target category (`category` stays `link`).
+
+All media code lives under **`src/shared/media/`**. Node-only modules are kept in the **`node/`** subdirectory so the filesystem path matches the package entry split.
+
+## Package entry split (important)
+
+| Consumer import | What you get | Source |
+|-----------------|--------------|--------|
+| `from "target-supabase-sdk"` | Browser-safe helpers only | `shared/media/index.ts` → `browser.ts` |
+| `from "target-supabase-sdk/node"` | + register / availability / probe | `shared/media/node/` → `node.ts` |
+
+There is **no** public subpath like `target-supabase-sdk/shared/media/node` — consumers always use the package `/node` entry.
+
+**Do not** re-export anything from `node/` in `index.ts` / `browser.ts`. Those files import `node:fs` / `node:crypto` / `node:path`. Pulling them into the default entry breaks Chrome/Webpack bundles (`verify-browser-entry` will fail).
+
+```text
+src/shared/media/
+  index.ts              ← browser-safe barrel ONLY (never export ./node)
+  media.interface.ts
+  media.build.ts
+  media.mime.ts
+  media.name.ts
+  media.query.ts
+  README.md
+  node/                 ← Node-only (fs / register)
+    index.ts            ← barrel for src/node.ts only
+    media.access.ts
+    media.service.ts
+```
+
+### Correct consumer imports
+
+```typescript
+// Default / browser — draft, mime, name, filters
+import {
+  buildMediaLinkDraft,
+  buildMediaNameFromLocator,
+  MEDIA_VALUES,
+  mediaLinkDedupFilters,
+} from "target-supabase-sdk";
+
+// Node workers / CLI — dedup + availability + register
+import {
+  findMediaLink,
+  checkMediaAvailability,
+  registerMediaLink,
+} from "target-supabase-sdk/node";
+```
+
+### Incorrect
+
+```typescript
+// BAD: Node-only APIs are not on the default entry
+import { registerMediaLink } from "target-supabase-sdk";
+```
+
+Internal SDK code:
+
+- Browser-safe leaves: `from "../media.build"` (etc.)
+- Node leaves: `from "./media.access"` inside `node/`, or `from "../shared/media/node"` from `src/node.ts`
+- Never pull `./node` through the parent `index.ts`
+
+---
+
+## Link field rules
+
+| Field | Rule |
+|-------|------|
+| `value` | `video` \| `audio` \| `image` \| `image-list` |
+| `details.loaderKey` | Always equals `value` |
+| `name` | Caller-provided unique key (or `buildMediaNameFromLocator`) |
+| `tagList` / `description` | Caller-defined (e.g. producer / scene tags) |
+| `details.manifestVersion` | `0` (via `buildLinkTargetDraft`) |
+| `details.preview` | `""` |
+
+## `details.original`
+
+| Key | Single file (`video`/`audio`/`image`) | `image-list` |
+|-----|----------------------------------------|--------------|
+| `storageProvider` | Host / backend id (e.g. `windows-storage:HOSTNAME`) | same |
+| `locator` | Absolute file path | Absolute **directory** path |
+| `contentHash` | SHA-256 hex (`MEDIA_CONTENT_HASH_ALGORITHM`) | `""` |
+| `size` | Byte length | File count (immediate children only, non-recursive) |
+| `mimeType` | e.g. `video/mp4` | `""` |
+
+`image-list` rules:
+
+1. `locator` must be an **absolute** directory path.
+2. Only **one level** under that directory is considered (no recursion).
+3. `size` counts **files** in that level (directories among children are ignored).
+
+## Register flow (`registerMediaLink`)
+
+1. **Dedup** — `category` + `value` + `name` via `findMediaLink`. If present → `{ id, created: false }`.
+2. **Availability** — `storageProvider` must equal `localStorageProvider` (typically `LOCAL_STORAGE_PROVIDER` from the service `.env`); `locator` absolute and reachable.
+3. **Probe** — stream SHA-256 / `stat` / MIME (or directory file count for `image-list`).
+4. **Insert** — `buildMediaLinkDraft` → `postTarget` (race → re-find).
+
+## Env (Node hosts)
+
+| Variable | Role |
+|----------|------|
+| `LOCAL_STORAGE_PROVIDER` | This machine’s storage id; pass as `localStorageProvider` into availability / register |
+
+Cross-host `storageProvider` cannot be verified on the current process — availability returns `ok: false`.
+
+See `.cursor/skills/media-link/SKILL.md`.

package/src/shared/media/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Media Link — browser-safe barrel only.
+ *
+ * Node-only code lives in `./node/` and is exported from `src/node.ts`,
+ * never from this file (see README.md).
+ */
+
+export type { BuildMediaLinkDraftInput } from "./media.build";
+export { buildMediaLinkDraft } from "./media.build";
+export type { MediaOriginal, MediaValue } from "./media.interface";
+export {
+    isMediaValue,
+    MEDIA_CONTENT_HASH_ALGORITHM,
+    MEDIA_CONTENT_HASH_PREFIX_LENGTH,
+    MEDIA_VALUES,
+} from "./media.interface";
+export { guessMediaMime } from "./media.mime";
+export { buildMediaNameFromLocator } from "./media.name";
+export { mediaLinkDedupFilters } from "./media.query";

package/src/shared/media/media.build.ts

@@ -0,0 +1,69 @@
+import type { TargetDraft } from "../../core.interface";
+import { buildLinkTargetDraft } from "../../link/link.build";
+import type { Link } from "../../link/link.interface";
+import { isMediaValue, type MediaOriginal, type MediaValue } from "./media.interface";
+
+export interface BuildMediaLinkDraftInput {
+    value: MediaValue;
+    name: string;
+    storageProvider: string;
+    locator: string;
+    contentHash: string;
+    size: number;
+    mimeType: string;
+    description?: string;
+    tagList?: string[];
+}
+
+/**
+ * Assemble a media {@link Link} draft (`category=link`, `loaderKey === value`).
+ * Does not validate filesystem or write to Supabase.
+ */
+export function buildMediaLinkDraft(input: BuildMediaLinkDraftInput): TargetDraft<Link> {
+    if (!isMediaValue(input.value)) {
+        throw new Error(`buildMediaLinkDraft: unsupported media value: ${String(input.value)}`);
+    }
+    const name = input.name.trim();
+    if (name === "") {
+        throw new Error("buildMediaLinkDraft: name is empty");
+    }
+    const storageProvider = input.storageProvider.trim();
+    if (storageProvider === "") {
+        throw new Error("buildMediaLinkDraft: storageProvider is empty");
+    }
+    const locator = input.locator.trim();
+    if (locator === "") {
+        throw new Error("buildMediaLinkDraft: locator is empty");
+    }
+    if (!Number.isFinite(input.size) || input.size < 0) {
+        throw new Error("buildMediaLinkDraft: size must be a non-negative number");
+    }
+
+    const isList = input.value === "image-list";
+    const contentHash = isList ? "" : input.contentHash.trim().toLowerCase();
+    const mimeType = isList ? "" : input.mimeType.trim();
+    if (!isList && contentHash === "") {
+        throw new Error("buildMediaLinkDraft: contentHash is required for single-file media");
+    }
+    if (!isList && mimeType === "") {
+        throw new Error("buildMediaLinkDraft: mimeType is required for single-file media");
+    }
+
+    const original: MediaOriginal = {
+        storageProvider,
+        locator,
+        contentHash,
+        size: Math.floor(input.size),
+        mimeType,
+    };
+
+    return buildLinkTargetDraft({
+        name,
+        value: input.value,
+        description: input.description ?? "",
+        preview: "",
+        loaderKey: input.value,
+        tagList: input.tagList ?? [],
+        original,
+    });
+}

package/src/shared/media/media.interface.ts

@@ -0,0 +1,45 @@
+/**
+ * Media Link protocol — Link rows with value/loaderKey in {@link MEDIA_VALUES}.
+ * No separate Target category; category remains `link`.
+ */
+
+/** Fixed digest algorithm for single-file media `contentHash`. */
+export const MEDIA_CONTENT_HASH_ALGORITHM = "sha256" as const;
+
+/** Hex prefix length for {@link buildMediaNameFromLocator}. */
+export const MEDIA_CONTENT_HASH_PREFIX_LENGTH = 6;
+
+export const MEDIA_VALUES = ["video", "audio", "image", "image-list"] as const;
+
+/** Discriminator stored in both `Link.value` and `details.loaderKey`. */
+export type MediaValue = (typeof MEDIA_VALUES)[number];
+
+/**
+ * `Link.details.original` for media Links.
+ *
+ * - `locator` — absolute filesystem path, or (future) network URL keyed by `storageProvider`.
+ * - `image-list`: `locator` is an absolute directory path; only the **immediate** children
+ *   (one level, non-recursive) are counted. `contentHash` and `mimeType` are `""`;
+ *   `size` is the number of files in that directory (not bytes).
+ * - other values: `size` is byte length; `contentHash` is SHA-256 hex; `mimeType` from the file.
+ */
+export interface MediaOriginal {
+    storageProvider: string;
+    locator: string;
+    /**
+     * SHA-256 hex of file bytes, or `""` when `value === "image-list"`.
+     * Algorithm is always {@link MEDIA_CONTENT_HASH_ALGORITHM}.
+     */
+    contentHash: string;
+    /**
+     * Single-file media: byte length.
+     * `image-list`: number of files in the directory (one level).
+     */
+    size: number;
+    /** e.g. `video/mp4`, or `""` when `value === "image-list"`. */
+    mimeType: string;
+}
+
+export function isMediaValue(value: string): value is MediaValue {
+    return (MEDIA_VALUES as readonly string[]).includes(value);
+}

package/src/shared/media/media.mime.ts

@@ -0,0 +1,64 @@
+import type { MediaValue } from "./media.interface";
+
+const VIDEO_EXT_MIME: Record<string, string> = {
+    mp4: "video/mp4",
+    m4v: "video/mp4",
+    mov: "video/quicktime",
+    mkv: "video/x-matroska",
+    webm: "video/webm",
+    avi: "video/x-msvideo",
+    mpeg: "video/mpeg",
+    mpg: "video/mpeg",
+    wmv: "video/x-ms-wmv",
+    flv: "video/x-flv",
+    ts: "video/mp2t",
+    m2ts: "video/mp2t",
+};
+
+const AUDIO_EXT_MIME: Record<string, string> = {
+    wav: "audio/wav",
+    mp3: "audio/mpeg",
+    m4a: "audio/mp4",
+    aac: "audio/aac",
+    flac: "audio/flac",
+    ogg: "audio/ogg",
+    oga: "audio/ogg",
+    opus: "audio/opus",
+    wma: "audio/x-ms-wma",
+};
+
+const IMAGE_EXT_MIME: Record<string, string> = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    webp: "image/webp",
+    gif: "image/gif",
+    bmp: "image/bmp",
+    tif: "image/tiff",
+    tiff: "image/tiff",
+};
+
+function extensionOf(pathOrUrl: string): string {
+    const cleaned = pathOrUrl.split(/[?#]/)[0] ?? pathOrUrl;
+    const base = cleaned.replace(/\\/g, "/").split("/").pop() ?? cleaned;
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 || dot === base.length - 1) {
+        return "";
+    }
+    return base.slice(dot + 1).toLowerCase();
+}
+
+/** Guess MIME from path extension; `null` when unknown. */
+export function guessMediaMime(locator: string, value: Exclude<MediaValue, "image-list">): string | null {
+    const ext = extensionOf(locator);
+    if (ext === "") {
+        return null;
+    }
+    if (value === "video") {
+        return VIDEO_EXT_MIME[ext] ?? null;
+    }
+    if (value === "audio") {
+        return AUDIO_EXT_MIME[ext] ?? null;
+    }
+    return IMAGE_EXT_MIME[ext] ?? null;
+}

package/src/shared/media/media.name.ts

@@ -0,0 +1,33 @@
+import { MEDIA_CONTENT_HASH_PREFIX_LENGTH } from "./media.interface";
+
+/**
+ * `{basename}.{hash6}.{ext}` from an absolute (or path-like) locator and full content hash.
+ * Does not touch the filesystem.
+ */
+export function buildMediaNameFromLocator(locator: string, contentHash: string): string {
+    const trimmedLocator = locator.trim();
+    if (trimmedLocator === "") {
+        throw new Error("buildMediaNameFromLocator: locator is empty");
+    }
+    const hash = contentHash.trim().toLowerCase();
+    if (hash.length < MEDIA_CONTENT_HASH_PREFIX_LENGTH) {
+        throw new Error(
+            `buildMediaNameFromLocator: contentHash must be at least ${MEDIA_CONTENT_HASH_PREFIX_LENGTH} hex chars`,
+        );
+    }
+    const hash6 = hash.slice(0, MEDIA_CONTENT_HASH_PREFIX_LENGTH);
+
+    const normalized = trimmedLocator.replace(/\\/g, "/");
+    const base = normalized.split("/").pop() ?? normalized;
+    if (base === "" || base === "." || base === "..") {
+        throw new Error(`buildMediaNameFromLocator: invalid basename from locator: ${locator}`);
+    }
+
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0 || dot === base.length - 1) {
+        return `${base}.${hash6}`;
+    }
+    const stem = base.slice(0, dot);
+    const ext = base.slice(dot + 1);
+    return `${stem}.${hash6}.${ext}`;
+}

package/src/shared/media/media.query.ts

@@ -0,0 +1,13 @@
+import type { QueryFilter } from "../../core.interface";
+import { CategoryLink } from "../../link/link.interface";
+import type { MediaValue } from "./media.interface";
+
+/** Dedup key: `category=link` + `value` + `name` (matches register / find). */
+export function mediaLinkDedupFilters(input: { value: MediaValue; name: string }): QueryFilter[] {
+    const name = input.name.trim();
+    return [
+        { field: "category", operator: "eq", value: CategoryLink.LINK },
+        { field: "value", operator: "eq", value: input.value },
+        { field: "name", operator: "eq", value: name },
+    ];
+}

package/src/shared/media/node/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Node-only media surface — for `src/node.ts` / `target-supabase-sdk/node` only.
+ * Never re-export from `../index.ts` or `browser.ts`.
+ */
+
+export type { CheckMediaAvailabilityInput, MediaAvailabilityResult } from "./media.access";
+export { checkMediaAvailability, probeMediaOriginal } from "./media.access";
+export type {
+    FindMediaLinkInput,
+    RegisterMediaLinkInput,
+    RegisterMediaLinkResult,
+} from "./media.service";
+export { findMediaLink, registerMediaLink } from "./media.service";