target-supabase-sdk 0.2.23 → 0.2.24

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/trigger/trigger.api.ts

@@ -60,7 +60,12 @@ function enabledTriggerFilter() {
     return [{ field: TRIGGER_STATUS_FIELD, operator: "eq" as const, value: TriggerStatus.ENABLED }];
 }
 
-/** List all ENABLED triggers (Phase 1: in-memory due check). */
+/**
+ * List all ENABLED triggers. Due-check is in-memory on the caller:
+ * filter with `isTriggerDue`, then `patchTriggerFired` with `buildFireKey`
+ * (both from `trigger.utils`, exported on `/node`).
+ * Do not call this from TriggerNode (local interval runners only).
+ */
 export const scanEnabledTriggers = validateWithSchema(
     scanEnabledTriggersSchema,
     "scanEnabledTriggersSchema",