@agent-native/creative-context 0.0.0-beta-20260820202238

package/src/connectors/index.ts

@@ -0,0 +1,112 @@
+import { FigmaContextConnector } from "./figma.js";
+import { GoogleSlidesContextConnector } from "./google-slides.js";
+import { ManualContextConnector } from "./manual.js";
+import { NotionContextConnector } from "./notion.js";
+import { ContextImportConnectorRegistry } from "./registry.js";
+import { UploadContextConnector } from "./upload.js";
+import { WebsiteContextConnector } from "./website.js";
+
+const DEFAULT_CONNECTORS = [
+  new ManualContextConnector(),
+  new UploadContextConnector(),
+  new GoogleSlidesContextConnector(),
+  new FigmaContextConnector(),
+  new NotionContextConnector(),
+  new WebsiteContextConnector(),
+] as const;
+
+const defaultCreativeContextConnectorRegistry =
+  new ContextImportConnectorRegistry();
+
+export function registerDefaultCreativeContextConnectors(
+  registry = defaultCreativeContextConnectorRegistry,
+): ContextImportConnectorRegistry {
+  for (const connector of DEFAULT_CONNECTORS) {
+    if (!registry.has(connector.kind)) registry.register(connector);
+  }
+  return registry;
+}
+
+export function getCreativeContextConnectorRegistry(): ContextImportConnectorRegistry {
+  return registerDefaultCreativeContextConnectors();
+}
+
+export function createDefaultContextImportConnectorRegistry(): ContextImportConnectorRegistry {
+  return registerDefaultCreativeContextConnectors(
+    new ContextImportConnectorRegistry(),
+  );
+}
+
+export {
+  createDefaultContextConnectorExecutionContext,
+  createWorkspaceConnectionResolver,
+  type CreateContextConnectorExecutionContextOptions,
+} from "./context.js";
+export { FigmaContextConnector, figmaRecommendedFileKeys } from "./figma.js";
+export {
+  fetchFigmaNativeContextItems,
+  MAX_INLINE_NATIVE_CODE_BYTES,
+  nativeFidelityReportFromEntries,
+} from "./figma-native.js";
+export {
+  GOOGLE_SLIDES_CONTEXT_OAUTH_SCOPES,
+  GoogleSlidesContextConnector,
+  googleSlidesRecommendedPresentationIds,
+} from "./google-slides.js";
+export {
+  compileGoogleSlidesPresentation,
+  type CompiledGoogleSlide,
+  type CompiledGoogleSlideChild,
+  type GoogleSlidesNativeCompileOptions,
+  type SlidesNativeAssetRequest,
+  type SlidesNativeBounds,
+  type SlidesNativeFallbackRequest,
+} from "./google-slides-native.js";
+export { ManualContextConnector } from "./manual.js";
+export {
+  NotionContextConnector,
+  notionRecommendedRootPageIds,
+} from "./notion.js";
+export {
+  parseUploadedDocument,
+  type ParseDocumentInput,
+  type ParsedDocument,
+} from "./document-parser.js";
+export { ContextImportConnectorRegistry } from "./registry.js";
+export {
+  LayeredRenderedPageProvider,
+  type LayeredRenderedPageProviderOptions,
+  type RenderedPageMethod,
+  type RenderedPageProvider,
+  type RenderedPageRequest,
+  type RenderedPageResult,
+} from "./rendered-page.js";
+export {
+  brandKitDataFromExtraction,
+  buildDesignMarkdown,
+  extractRenderedDesignSystemFromUrl,
+  styleBriefFromRenderedDesign,
+  type ExtractRenderedDesignOptions,
+  type RenderedDesignExtraction,
+  type RenderedDesignExtractionStatus,
+} from "./rendered-design.js";
+export {
+  recommendContextRoots,
+  type ContextRootRecommendation,
+  type ContextRootRecommendationProvider,
+} from "./recommendations.js";
+export { smartDefaultExternalIds } from "./smart-defaults.js";
+export { UploadContextConnector } from "./upload.js";
+export { WebsiteContextConnector } from "./website.js";
+export type {
+  ContextConnectorExecutionContext,
+  ContextConnectorFetchRequest,
+  ContextConnectorFetchResult,
+  ContextConnectorInventoryItem,
+  ContextConnectorInventoryPage,
+  ContextConnectorInventoryRequest,
+  ContextConnectorKind,
+  ContextImportConnector,
+  ContextImportConnectorSummary,
+  ContextUploadContent,
+} from "./types.js";

package/src/connectors/manual.ts

@@ -0,0 +1,132 @@
+import { normalizeContextItem } from "./normalize.js";
+import {
+  asRecord,
+  cursorOffset,
+  positiveLimit,
+  stringValue,
+} from "./provider-response.js";
+import type {
+  ContextConnectorExecutionContext,
+  ContextConnectorFetchRequest,
+  ContextConnectorFetchResult,
+  ContextConnectorInventoryItem,
+  ContextConnectorInventoryPage,
+  ContextConnectorInventoryRequest,
+  ContextImportConnector,
+} from "./types.js";
+
+interface ManualEntry {
+  id: string;
+  title: string;
+  text: string;
+  kind: string;
+  canonicalUrl?: string;
+  mimeType?: string;
+  sourceModifiedAt?: string;
+  summary?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export class ManualContextConnector implements ContextImportConnector {
+  readonly kind = "manual" as const;
+  readonly label = "Manual text";
+  readonly supportsIncremental = false;
+
+  async inventory(
+    request: ContextConnectorInventoryRequest,
+    _context: ContextConnectorExecutionContext,
+  ): Promise<ContextConnectorInventoryPage> {
+    const entries = parseManualEntries(request.config);
+    const offset = cursorOffset(request.cursor);
+    const limit = positiveLimit(request.limit, 100, 1_000);
+    const slice = entries.slice(offset, offset + limit);
+    const nextOffset = offset + slice.length;
+    return {
+      items: slice.map((entry, index) => ({
+        externalId: entry.id,
+        kind: entry.kind,
+        title: entry.title,
+        ...(entry.canonicalUrl ? { canonicalUrl: entry.canonicalUrl } : {}),
+        ...(entry.mimeType ? { mimeType: entry.mimeType } : {}),
+        ...(entry.sourceModifiedAt
+          ? { sourceModifiedAt: entry.sourceModifiedAt }
+          : {}),
+        metadata: { entryIndex: offset + index },
+      })),
+      nextCursor: nextOffset < entries.length ? String(nextOffset) : null,
+      complete: nextOffset >= entries.length,
+      coverage: {
+        inspected: slice.length,
+        returned: slice.length,
+        truncated: nextOffset < entries.length,
+      },
+    };
+  }
+
+  async fetch(
+    request: ContextConnectorFetchRequest,
+    _context: ContextConnectorExecutionContext,
+  ): Promise<ContextConnectorFetchResult> {
+    const entry = findManualEntry(request.config, request.item);
+    return {
+      items: [
+        normalizeContextItem({
+          externalId: entry.id,
+          kind: entry.kind,
+          title: entry.title,
+          content: entry.text,
+          canonicalUrl: entry.canonicalUrl,
+          mimeType: entry.mimeType,
+          summary: entry.summary,
+          sourceModifiedAt: entry.sourceModifiedAt,
+          metadata: entry.metadata,
+        }),
+      ],
+    };
+  }
+}
+
+function parseManualEntries(config: Record<string, unknown>): ManualEntry[] {
+  if (!Array.isArray(config.items)) {
+    throw new Error("Manual connector config.items must be an array.");
+  }
+  return config.items.map((value, index) => {
+    const item = asRecord(value);
+    const id = stringValue(item?.id) ?? `manual-${index + 1}`;
+    const title = stringValue(item?.title) ?? `Manual context ${index + 1}`;
+    const text = stringValue(item?.text);
+    if (!text) throw new Error(`Manual context ${id} requires text.`);
+    if (text.length > 250_000) {
+      throw new Error(
+        `Manual context ${id} is too large for inline text; use the upload connector.`,
+      );
+    }
+    return {
+      id,
+      title,
+      text,
+      kind: stringValue(item?.kind) ?? "manual-document",
+      canonicalUrl: stringValue(item?.canonicalUrl),
+      mimeType: stringValue(item?.mimeType) ?? "text/plain",
+      sourceModifiedAt: stringValue(item?.sourceModifiedAt),
+      summary: stringValue(item?.summary),
+      metadata: asRecord(item?.metadata) ?? undefined,
+    };
+  });
+}
+
+function findManualEntry(
+  config: Record<string, unknown>,
+  inventoryItem: ContextConnectorInventoryItem,
+): ManualEntry {
+  const entries = parseManualEntries(config);
+  const index = Number(inventoryItem.metadata?.entryIndex);
+  const byIndex = Number.isInteger(index) ? entries[index] : undefined;
+  const entry =
+    byIndex?.id === inventoryItem.externalId
+      ? byIndex
+      : entries.find((candidate) => candidate.id === inventoryItem.externalId);
+  if (!entry)
+    throw new Error(`Manual context ${inventoryItem.externalId} not found.`);
+  return entry;
+}

package/src/connectors/normalize.spec.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  assertContextItemSqlTextLimits,
+  MAX_METADATA_BYTES,
+  MAX_MEDIA_LOCATOR_BYTES,
+  MAX_MEDIA_TEXT_BYTES,
+  MAX_NATIVE_CONTENT_BYTES,
+  MAX_SEARCHABLE_CONTENT_BYTES,
+  MAX_SUMMARY_BYTES,
+  normalizeContextItem,
+} from "./normalize.js";
+
+describe("normalizeContextItem SQL text limits", () => {
+  it("bounds emoji content and summaries by UTF-8 bytes without splitting code points", () => {
+    const item = normalizeContextItem({
+      externalId: "emoji",
+      kind: "document",
+      title: "Emoji",
+      content: "🙂".repeat(20_000),
+      summary: "🙂".repeat(3_000),
+    });
+
+    expect(Buffer.byteLength(item.content, "utf8")).toBe(
+      MAX_SEARCHABLE_CONTENT_BYTES,
+    );
+    expect(Array.from(item.content)).toHaveLength(
+      MAX_SEARCHABLE_CONTENT_BYTES / 4,
+    );
+    expect(Buffer.byteLength(item.summary!, "utf8")).toBe(MAX_SUMMARY_BYTES);
+    expect(Array.from(item.summary!)).toHaveLength(MAX_SUMMARY_BYTES / 4);
+    expect(item.content).not.toContain("�");
+    expect(item.summary).not.toContain("�");
+  });
+
+  it("uses the largest complete CJK prefix that fits the UTF-8 byte budget", () => {
+    const item = normalizeContextItem({
+      externalId: "cjk",
+      kind: "document",
+      title: "CJK",
+      content: "界".repeat(30_000),
+    });
+
+    const expectedCodePoints = Math.floor(MAX_SEARCHABLE_CONTENT_BYTES / 3);
+    expect(Array.from(item.content)).toHaveLength(expectedCodePoints);
+    expect(Buffer.byteLength(item.content, "utf8")).toBe(
+      expectedCodePoints * 3,
+    );
+    expect(Buffer.byteLength(item.content, "utf8")).toBeLessThanOrEqual(
+      MAX_SEARCHABLE_CONTENT_BYTES,
+    );
+  });
+
+  it("rejects oversized native HTML intact instead of truncating its markup", () => {
+    const html = `<div class="fmd-slide">${"界".repeat(MAX_NATIVE_CONTENT_BYTES / 3)}</div>`;
+
+    expect(() =>
+      normalizeContextItem({
+        externalId: "oversized-native",
+        kind: "google-slides-slide",
+        title: "Oversized native slide",
+        mimeType: "text/html",
+        content: html,
+        metadata: {
+          nativeArtifact: { app: "slides", format: "slides-html" },
+        },
+      }),
+    ).toThrow(/native content.*exceeds.*split the artifact/i);
+  });
+
+  it("rejects oversized structured metadata and media text before SQL writes", () => {
+    const oversizedMetadata = normalizeContextItem({
+      externalId: "oversized-metadata",
+      kind: "presentation",
+      title: "Oversized metadata",
+      content: "small",
+      metadata: { speakerNotes: "x".repeat(MAX_METADATA_BYTES) },
+    });
+    expect(() => assertContextItemSqlTextLimits(oversizedMetadata)).toThrow(
+      /item metadata.*exceeds.*private blob storage/i,
+    );
+
+    const oversizedMedia = normalizeContextItem({
+      externalId: "oversized-media",
+      kind: "presentation",
+      title: "Oversized media",
+      content: "small",
+      media: [
+        {
+          kind: "image",
+          url: "https://example.com/image.png",
+          ocrText: "x".repeat(MAX_MEDIA_TEXT_BYTES + 1),
+          metadata: { providerPayload: "small" },
+        },
+      ],
+    });
+    expect(() => assertContextItemSqlTextLimits(oversizedMedia)).toThrow(
+      /media OCR text.*exceeds.*private blob storage/i,
+    );
+
+    const oversizedProvenance = normalizeContextItem({
+      externalId: "oversized-provenance",
+      kind: "presentation",
+      title: "Oversized provenance",
+      content: "small",
+      provenance: { providerPayload: "x".repeat(MAX_METADATA_BYTES) },
+    });
+    expect(() => assertContextItemSqlTextLimits(oversizedProvenance)).toThrow(
+      /item provenance.*exceeds.*private blob storage/i,
+    );
+
+    const inlineDataUrl = normalizeContextItem({
+      externalId: "inline-media",
+      kind: "presentation",
+      title: "Inline media",
+      content: "small",
+      media: [
+        {
+          kind: "image",
+          url: "data:image/png;base64,AAAA",
+        },
+      ],
+    });
+    expect(() => assertContextItemSqlTextLimits(inlineDataUrl)).toThrow(
+      /media URL cannot be an inline data URL/i,
+    );
+
+    const oversizedLocator = normalizeContextItem({
+      externalId: "oversized-locator",
+      kind: "presentation",
+      title: "Oversized locator",
+      content: "small",
+      media: [
+        {
+          kind: "image",
+          url: `https://example.com/${"x".repeat(MAX_MEDIA_LOCATOR_BYTES)}`,
+        },
+      ],
+    });
+    expect(() => assertContextItemSqlTextLimits(oversizedLocator)).toThrow(
+      /media URL.*exceeds.*private blob storage/i,
+    );
+  });
+});