target-supabase-sdk 0.2.22 → 0.2.24

package/src/shared/idea/VALIDATION-MATRIX.md

@@ -0,0 +1,69 @@
+# Idea Link validation matrix
+
+Single reference for **where** each constraint is enforced. Limits match upload-service `POST/PATCH /v0/upload/idea` and paste-image behavior.
+
+Legend: **Z** = `ideaOriginalSchema` / `ideaCreateSchema` / `ideaUpdateSchema` (Zod); **B** = `buildIdeaLinkDraft` / `buildIdeaImageLinkDraft`; **H** = upload-service HTTP handler (Zod on request body); **P** = paste-image route (MIME, size, empty buffer).
+
+## Row identity
+
+| Rule | Z | B | H | Notes |
+|------|---|---|---|-------|
+| `category=link` | — | — | — | Set by `createTarget` / SDK category, not in draft builder |
+| `value=idea` | — | ✓ | — | Fixed in builders |
+| `loaderKey=idea` | — | ✓ | — | Same as `value` |
+| Text `name` non-empty | ✓ create | ✓ | ✓ | `ideaCreateSchema` / builder |
+| Text `name` max 500 | ✓ create/update | ✓ | ✓ | |
+| Text `name` ≠ `idea.image` | — | ✓ | — | Use `buildIdeaImageLinkDraft` for images |
+| Image `name=idea.image` | — | ✓ | — | Fixed in `buildIdeaImageLinkDraft` |
+| No title uniqueness / dedup | — | — | — | By design |
+
+## `details.original`
+
+| Field | Z | B | H | Limit / rule |
+|-------|---|---|---|----------------|
+| `content` | ✓ min 1, max 100_000 | ✓ same | ✓ create/update | Text body or image SHA-256 hex |
+| `reviewList` | ✓ max 32 items, each 1–8000 | ✓ | ✓ | Normalized (trim, dedupe) |
+| `url` | ✓ max 2000, default `""` | ✓ | ✓ | Image: temp download URL required in builder |
+| `heat` | ✓ int ≥ 0, default 0 | ✓ floor 0 | — | PATCH +1 is upload-service only |
+| Image `reviewList` | — | ✓ `[]` | — | Builder fixed |
+| Image `heat` | — | ✓ `0` | — | Builder fixed |
+
+## `tagList`
+
+| Rule | Z create | B text | B image | Notes |
+|------|----------|--------|---------|-------|
+| Max 32 tags | ✓ | ✓ | ✓ | |
+| Each tag 1–128 chars | ✓ | ✓ | — | Builder checks length on text tags |
+| Default image tags | — | — | ✓ `[ ".raw" ]` if omitted | |
+| Quick-note `.raw` | — | — | — | Extension local wrapper only |
+
+## Paste-image (bytes → Link)
+
+| Rule | P | B image | Node hash/locator |
+|------|---|---------|-------------------|
+| MIME whitelist | ✓ | — | — |
+| Non-empty buffer | ✓ | — | — |
+| Max file size | ✓ `TEMP_FS_MAX_FILE_SIZE` | — | — |
+| Optional paste `content` field | — | — | upload-service: caption → `original.content`; empty → hash |
+| Content hash (file path) | — | — | `hashIdeaPasteImage` + `buildIdeaPasteRelativePath` |
+| Stored `original.content` | ✓ min 1 | ✓ | user text or hash fallback |
+| Temp path `idea/paste/{hash}.{ext}` | — | — | `buildIdeaPasteRelativePath` |
+| `original.url` temp download | — | ✓ non-empty URL | `buildIdeaTempDownloadLocator` |
+| Content-hash dedup before create | — | — | **Not implemented** |
+
+## Query / read
+
+| Rule | SDK | upload-service |
+|------|-----|----------------|
+| Filter by `value=idea` | `ideaLinkValueFilters` | list/get/delete |
+| Image-only list | `ideaImageLinkFilters` | `linkName=idea.image` |
+| Parse row `original` | `parseIdeaOriginal` | `toIdeaView` throws if invalid |
+| Search `name` / `content` ilike | — | list API only |
+
+## Error style
+
+| Layer | Behavior |
+|-------|----------|
+| Zod (H / optional client) | Field errors in HTTP 400 |
+| `buildIdea*Draft` | `throw new Error("buildIdeaLinkDraft: …")` |
+| `parseIdeaOriginal` | Returns `null` (no throw) |

package/src/shared/idea/idea.build.ts

@@ -0,0 +1,160 @@
+import type { TargetDraft } from "../../core.interface";
+import { buildLinkTargetDraft } from "../../link/link.build";
+import type { Link } from "../../link/link.interface";
+import {
+    IDEA_IMAGE_LINK_NAME,
+    IDEA_IMAGE_TAG_RAW,
+    IDEA_LINK_VALUE,
+    type IdeaOriginal,
+    isIdeaImageLinkName,
+} from "./idea.interface";
+import { normalizeStringList } from "./idea.normalize";
+
+export interface BuildIdeaLinkDraftInput {
+    /** Article title — Link.name (not used for image ideas). */
+    name: string;
+    /** Body or image content hash — `details.original.content`. */
+    content: string;
+    reviewList?: readonly string[];
+    url?: string;
+    heat?: number;
+    tagList?: readonly string[];
+    description?: string;
+    preview?: string;
+}
+
+export interface BuildIdeaImageLinkDraftInput {
+    /** SHA-256 hex of image bytes — stored in `details.original.content`. */
+    contentHash: string;
+    /** Temp download or other absolute URL — `details.original.url`. */
+    url: string;
+    heat?: number;
+    tagList?: readonly string[];
+    description?: string;
+    preview?: string;
+}
+
+function resolveIdeaOriginal(input: {
+    content: string;
+    reviewList?: readonly string[];
+    url?: string;
+    heat?: number;
+}): IdeaOriginal {
+    const content = input.content.trim();
+    if (content === "") {
+        throw new Error("buildIdeaLinkDraft: content is empty");
+    }
+    if (content.length > 100_000) {
+        throw new Error("buildIdeaLinkDraft: content exceeds 100000 characters");
+    }
+
+    const url = input.url?.trim() ?? "";
+    if (url.length > 2000) {
+        throw new Error("buildIdeaLinkDraft: url exceeds 2000 characters");
+    }
+
+    const reviewList = normalizeStringList(input.reviewList);
+    if (reviewList.length > 32) {
+        throw new Error("buildIdeaLinkDraft: reviewList exceeds 32 entries");
+    }
+    for (const entry of reviewList) {
+        if (entry.length > 8000) {
+            throw new Error("buildIdeaLinkDraft: reviewList entry exceeds 8000 characters");
+        }
+    }
+
+    return {
+        content,
+        reviewList,
+        url,
+        heat: Math.max(0, Math.floor(input.heat ?? 0)),
+    };
+}
+
+/**
+ * Assemble a text idea {@link Link} draft (`category=link`, `loaderKey === value === "idea"`).
+ * Does not write to Supabase or enforce title uniqueness.
+ */
+export function buildIdeaLinkDraft(input: BuildIdeaLinkDraftInput): TargetDraft<Link> {
+    const name = input.name.trim();
+    if (name === "") {
+        throw new Error("buildIdeaLinkDraft: name is empty");
+    }
+    if (name.length > 500) {
+        throw new Error("buildIdeaLinkDraft: name exceeds 500 characters");
+    }
+    if (isIdeaImageLinkName(name)) {
+        throw new Error("buildIdeaLinkDraft: name is reserved for image ideas; use buildIdeaImageLinkDraft");
+    }
+
+    const tagList = normalizeStringList(input.tagList);
+    if (tagList.length > 32) {
+        throw new Error("buildIdeaLinkDraft: tagList exceeds 32 entries");
+    }
+    for (const tag of tagList) {
+        if (tag.length > 128) {
+            throw new Error("buildIdeaLinkDraft: tag exceeds 128 characters");
+        }
+    }
+
+    const original = resolveIdeaOriginal({
+        content: input.content,
+        reviewList: input.reviewList,
+        url: input.url,
+        heat: input.heat,
+    });
+
+    return buildLinkTargetDraft({
+        name,
+        value: IDEA_LINK_VALUE,
+        description: input.description ?? "",
+        preview: input.preview ?? "",
+        loaderKey: IDEA_LINK_VALUE,
+        tagList,
+        original,
+    });
+}
+
+/**
+ * Assemble a clipboard-image idea Link (`name=idea.image`, `value=idea`).
+ * Caller stores bytes and supplies hash + temp URL; no dedup by content hash.
+ */
+export function buildIdeaImageLinkDraft(input: BuildIdeaImageLinkDraftInput): TargetDraft<Link> {
+    const contentHash = input.contentHash.trim();
+    if (contentHash === "") {
+        throw new Error("buildIdeaImageLinkDraft: contentHash is empty");
+    }
+    if (contentHash.length > 100_000) {
+        throw new Error("buildIdeaImageLinkDraft: contentHash exceeds 100000 characters");
+    }
+
+    const url = input.url.trim();
+    if (url === "") {
+        throw new Error("buildIdeaImageLinkDraft: url is empty");
+    }
+    if (url.length > 2000) {
+        throw new Error("buildIdeaImageLinkDraft: url exceeds 2000 characters");
+    }
+
+    const tagList = normalizeStringList(input.tagList ?? [IDEA_IMAGE_TAG_RAW]);
+    if (tagList.length === 0) {
+        throw new Error("buildIdeaImageLinkDraft: tagList is empty");
+    }
+
+    const original: IdeaOriginal = {
+        content: contentHash,
+        reviewList: [],
+        url,
+        heat: Math.max(0, Math.floor(input.heat ?? 0)),
+    };
+
+    return buildLinkTargetDraft({
+        name: IDEA_IMAGE_LINK_NAME,
+        value: IDEA_LINK_VALUE,
+        description: input.description ?? "",
+        preview: input.preview ?? "",
+        loaderKey: IDEA_LINK_VALUE,
+        tagList,
+        original,
+    });
+}

package/src/shared/idea/idea.interface.ts

@@ -0,0 +1,34 @@
+/**
+ * Idea Link protocol — Link rows with `value` / `loaderKey` === {@link IDEA_LINK_VALUE}.
+ * Clipboard images use fixed `name` {@link IDEA_IMAGE_LINK_NAME} (not a separate value).
+ */
+
+export const IDEA_LINK_VALUE = "idea" as const;
+
+/** Discriminator stored in both `Link.value` and `details.loaderKey`. */
+export type IdeaLinkValue = typeof IDEA_LINK_VALUE;
+
+/** Link.name for clipboard-image ideas (distinct from title-based text ideas). */
+export const IDEA_IMAGE_LINK_NAME = "idea.image" as const;
+
+/** Default tag for raw captures (quick-note, paste-image). Leading `.` = system tag. */
+export const IDEA_IMAGE_TAG_RAW = ".raw" as const;
+
+/** Temp sandbox prefix for pasted images (`TEMP_FS_ROOT` on upload-service). */
+export const IDEA_IMAGE_TEMP_DIR = "idea/paste" as const;
+
+/** `Link.details.original` for idea Links (text and image). */
+export interface IdeaOriginal {
+    content: string;
+    reviewList: string[];
+    url: string;
+    heat: number;
+}
+
+export function isIdeaLinkValue(value: string): value is IdeaLinkValue {
+    return value === IDEA_LINK_VALUE;
+}
+
+export function isIdeaImageLinkName(name: string): boolean {
+    return name.trim() === IDEA_IMAGE_LINK_NAME;
+}

package/src/shared/idea/idea.normalize.ts

@@ -0,0 +1,17 @@
+/** Trim, dedupe, and drop empty strings from tag/review lists. */
+export function normalizeStringList(raw: readonly string[] | undefined | null): string[] {
+    if (raw == null || raw.length === 0) {
+        return [];
+    }
+    const seen = new Set<string>();
+    const out: string[] = [];
+    for (const item of raw) {
+        const text = item.trim();
+        if (text === "" || seen.has(text)) {
+            continue;
+        }
+        seen.add(text);
+        out.push(text);
+    }
+    return out;
+}

package/src/shared/idea/idea.parse.ts

@@ -0,0 +1,16 @@
+import type { IdeaOriginal } from "./idea.interface";
+import { normalizeStringList } from "./idea.normalize";
+import { ideaOriginalSchema } from "./idea.schema";
+
+export function parseIdeaOriginal(original: unknown): IdeaOriginal | null {
+    const parsed = ideaOriginalSchema.safeParse(original);
+    if (!parsed.success) {
+        return null;
+    }
+    return {
+        content: parsed.data.content,
+        reviewList: normalizeStringList(parsed.data.reviewList),
+        url: parsed.data.url,
+        heat: parsed.data.heat,
+    };
+}

package/src/shared/idea/idea.query.ts

@@ -0,0 +1,16 @@
+import type { QueryFilter } from "../../core.interface";
+import { CategoryLink } from "../../link/link.interface";
+import { IDEA_IMAGE_LINK_NAME, IDEA_LINK_VALUE } from "./idea.interface";
+
+/** List/get filters: `category=link` and `value=idea` (do not filter on `details.loaderKey`). */
+export function ideaLinkValueFilters(): QueryFilter[] {
+    return [
+        { field: "category", operator: "eq", value: CategoryLink.LINK },
+        { field: "value", operator: "eq", value: IDEA_LINK_VALUE },
+    ];
+}
+
+/** Clipboard-image ideas only (`name=idea.image`). */
+export function ideaImageLinkFilters(): QueryFilter[] {
+    return [...ideaLinkValueFilters(), { field: "name", operator: "eq", value: IDEA_IMAGE_LINK_NAME }];
+}

package/src/shared/idea/idea.schema.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+/** Runtime shape of `Link.details.original` for value=idea. */
+export const ideaOriginalSchema = z.object({
+    content: z.string().trim().min(1).max(100_000),
+    reviewList: z.array(z.string().trim().min(1).max(8000)).max(32).default([]),
+    url: z.string().trim().max(2000).default(""),
+    heat: z.number().int().min(0).default(0),
+});
+
+const ideaTagSchema = z.string().trim().min(1).max(128);
+
+/** HTTP / API create body limits (upload-service `POST /v0/upload/idea`). */
+export const ideaCreateSchema = z.object({
+    name: z.string().trim().min(1, "name is required").max(500),
+    content: z.string().trim().min(1, "content is required").max(100_000),
+    reviewList: z.array(z.string().trim().min(1).max(8000)).max(32).default([]),
+    url: z.string().trim().max(2000).default(""),
+    tagList: z.array(ideaTagSchema).max(32).default([]),
+});
+
+export type IdeaCreateSchemaInput = z.infer<typeof ideaCreateSchema>;
+
+export const ideaUpdateSchema = z.object({
+    name: z.string().trim().min(1).max(500).optional(),
+    content: z.string().trim().min(1).max(100_000).optional(),
+    reviewList: z.array(z.string().trim().min(1).max(8000)).max(32).optional(),
+    url: z.string().trim().max(2000).optional(),
+    tagList: z.array(ideaTagSchema).max(32).optional(),
+});
+
+export type IdeaUpdateSchemaInput = z.infer<typeof ideaUpdateSchema>;

package/src/shared/idea/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Idea Link — browser-safe public barrel only.
+ *
+ * Node-only code lives in `./node/` and is exported from `src/node.ts`.
+ */
+
+export type { BuildIdeaImageLinkDraftInput, BuildIdeaLinkDraftInput } from "./idea.build";
+export { buildIdeaImageLinkDraft, buildIdeaLinkDraft } from "./idea.build";
+export type { IdeaOriginal } from "./idea.interface";
+export {
+    IDEA_IMAGE_LINK_NAME,
+    IDEA_IMAGE_TAG_RAW,
+    IDEA_IMAGE_TEMP_DIR,
+    IDEA_LINK_VALUE,
+    isIdeaImageLinkName,
+} from "./idea.interface";
+export { normalizeStringList } from "./idea.normalize";
+export { parseIdeaOriginal } from "./idea.parse";
+export { ideaLinkValueFilters } from "./idea.query";
+export type { IdeaCreateSchemaInput, IdeaUpdateSchemaInput } from "./idea.schema";
+export { ideaCreateSchema, ideaUpdateSchema } from "./idea.schema";

package/src/shared/idea/node/idea.hash.ts

@@ -0,0 +1,6 @@
+import { createHash } from "node:crypto";
+
+/** SHA-256 hex of image bytes (filename + `details.original.content` for paste-image ideas). */
+export function hashIdeaPasteImage(buffer: Buffer): string {
+    return createHash("sha256").update(buffer).digest("hex");
+}

package/src/shared/idea/node/idea.locator.ts

@@ -0,0 +1,61 @@
+import { IDEA_IMAGE_TEMP_DIR } from "../idea.interface";
+
+/** Path suffix on upload-service public URL for temp file download. */
+export const IDEA_TEMP_DOWNLOAD_PATH_SUFFIX = "/v0/upload/temp/download";
+
+/** Flat path under temp sandbox: `idea/paste/{sha256}.{ext}`. */
+export function buildIdeaPasteRelativePath(contentHash: string, ext: string): string {
+    const hash = contentHash.trim();
+    const extension = ext.trim().replace(/^\./, "");
+    if (hash === "" || extension === "") {
+        throw new Error("buildIdeaPasteRelativePath: contentHash and ext are required");
+    }
+    return `${IDEA_IMAGE_TEMP_DIR}/${hash}.${extension}`;
+}
+
+function normalizeRelativeSandboxPath(path: string): string | null {
+    const normalized = path.replace(/\\/g, "/").trim();
+    if (normalized === "" || normalized.startsWith("/") || normalized.includes("..")) {
+        return null;
+    }
+    return normalized;
+}
+
+/** Build absolute locator stored in `details.original.url`. */
+export function buildIdeaTempDownloadLocator(relativePath: string, publicBaseUrl: string): string {
+    const sanitized = normalizeRelativeSandboxPath(relativePath);
+    if (sanitized == null) {
+        throw new Error("buildIdeaTempDownloadLocator: invalid relativePath");
+    }
+    const base = publicBaseUrl.trim().replace(/\/+$/, "");
+    const url = new URL(`${base}${IDEA_TEMP_DOWNLOAD_PATH_SUFFIX}`);
+    url.searchParams.set("path", sanitized);
+    return url.href;
+}
+
+/** Parse temp download URL → sandbox-relative path, or null when not a temp download URL. */
+export function parseIdeaTempDownloadLocator(locator: string): string | null {
+    const trimmed = locator.trim();
+    if (trimmed === "") {
+        return null;
+    }
+
+    let parsed: URL;
+    try {
+        parsed = new URL(trimmed, "http://localhost");
+    } catch {
+        return null;
+    }
+
+    const pathname = parsed.pathname.replace(/\\/g, "/");
+    if (!pathname.endsWith(IDEA_TEMP_DOWNLOAD_PATH_SUFFIX)) {
+        return null;
+    }
+
+    const pathParam = parsed.searchParams.get("path");
+    if (pathParam == null || pathParam.trim() === "") {
+        return null;
+    }
+
+    return normalizeRelativeSandboxPath(pathParam.trim());
+}

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

@@ -0,0 +1,7 @@
+export { hashIdeaPasteImage } from "./idea.hash";
+export {
+    buildIdeaPasteRelativePath,
+    buildIdeaTempDownloadLocator,
+    IDEA_TEMP_DOWNLOAD_PATH_SUFFIX,
+    parseIdeaTempDownloadLocator,
+} from "./idea.locator";

package/src/shared/media/README.md

@@ -106,4 +106,4 @@ Internal SDK code:
 
 Cross-host `storageProvider` cannot be verified on the current process — availability returns `ok: false`.
 
-See `.cursor/skills/media-link/SKILL.md`.
+See `.cursor/skills/link-conventions/SKILL.md`.

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

@@ -1,13 +1,8 @@
 import type { QueryFilter } from "../../core.interface";
-import { CategoryLink } from "../../link/link.interface";
+import { linkDedupFilters } from "../../link/link.query";
 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 },
-    ];
+    return linkDedupFilters(input);
 }

package/src/shared/review/review.query.ts

@@ -1,5 +1,5 @@
 import type { QueryFilter } from "../../core.interface";
-import { CategoryLink } from "../../link/link.interface";
+import { linkDedupFilters } from "../../link/link.query";
 import { REVIEW_VALUE } from "./review.interface";
 
 /**
@@ -7,10 +7,5 @@ import { REVIEW_VALUE } from "./review.interface";
  * Many rows may match — the SDK does not define dedup for reviews.
  */
 export function reviewLinksForNameFilters(name: string): QueryFilter[] {
-    const trimmed = name.trim();
-    return [
-        { field: "category", operator: "eq", value: CategoryLink.LINK },
-        { field: "value", operator: "eq", value: REVIEW_VALUE },
-        { field: "name", operator: "eq", value: trimmed },
-    ];
+    return linkDedupFilters({ value: REVIEW_VALUE, name });
 }

package/src/shared/utils/config-path.utils.ts

@@ -15,7 +15,7 @@ export function getConfigFileDir(configFilePath: string): string {
  * - Absolute `pathInConfig` → returned as-is
  * - Relative `pathInConfig` → `resolve(dirname(configFilePath), pathInConfig)`
  *
- * **Not** relative to `process.cwd()`. See `.cursor/skills/config-file-relative-paths/SKILL.md`.
+ * **Not** relative to `process.cwd()`. See `.cursor/skills/task-local-discovery/SKILL.md`.
  */
 export function resolvePathFromConfigFile(configFilePath: string, pathInConfig: string): string {
     const trimmed = pathInConfig.trim();

package/src/shared/utils/postgrest.utils.ts

@@ -1,7 +1,7 @@
 /**
  * PostgREST / Supabase JS client helpers for `target` table filters.
  *
- * @see `.cursor/skills/postgrest-query-filters/SKILL.md`
+ * @see `.cursor/skills/target-list-query/SKILL.md`
  */
 
 /**

package/src/task/index.ts

@@ -1,6 +1,6 @@
 /**
  * Task domain public API — curated re-exports only.
- * Internal modules (local-task-registry, task-repo-context, task.utils) stay private.
+ * Internal modules (local-task-registry, task-repo-context) stay private.
  */
 
 export type {

package/src/task/local-task-registry.ts

@@ -244,7 +244,7 @@ async function runBootstrapScan(options: BootstrapLocalTasksOptions): Promise<Bo
  * ./tasks/my-task/index.mjs
  * ```
  *
- * `taskDir` / `entry` paths are relative to **their config file's directory** (see config-file-relative-paths skill).
+ * `taskDir` / `entry` paths are relative to **their config file's directory** (see task-local-discovery skill).
  *
  * Legacy fallback: `./task.config.js` at project root (`taskDir: "./tasks"`).
  */

package/src/task/task-node.ts

@@ -2,7 +2,7 @@ import { isOptimisticLockResponse } from "../core.api";
 import { BaseNodeRuntime, LOG_TOPIC_NODE, type NodeLoopContext } from "../node/node-runtime.base";
 import { createLogger, createScope, type LoggerWithScope, withModule } from "../shared/log";
 import { getErrorMessage, toError } from "../shared/utils/error.utils";
-import { patchChangeTaskStatus, patchClaimTask } from "./task.api";
+import { type PatchClaimTaskPayload, patchChangeTaskStatus, patchClaimTask } from "./task.api";
 import { CRITICAL_UNKNOWN_TASK_TRACE_ID, LOG_TOPIC_TASK } from "./task.constant";
 import { TaskStatusAction } from "./task.interface";
 import { TaskManager, type TaskRunResult } from "./task-manager";
@@ -19,6 +19,11 @@ class TaskNode extends BaseNodeRuntime {
         return [...this._availableTaskList];
     }
 
+    /** Optional claim filters passed to {@link patchClaimTask} (e.g. name prefix per task type). */
+    protected getPatchClaimTaskOptions(): Pick<PatchClaimTaskPayload, "namePrefixList"> {
+        return {};
+    }
+
     constructor() {
         super("taskNode");
     }
@@ -63,6 +68,7 @@ class TaskNode extends BaseNodeRuntime {
             nodeId,
             availableTaskList: [...availableTaskList],
             traceId: loopTraceId,
+            ...this.getPatchClaimTaskOptions(),
         });
         if (claimError) {
             if (isOptimisticLockResponse(claimError)) {