@struktur/sdk 2.1.2 → 2.2.0

package/src/artifacts/input.test.ts

@@ -1,243 +0,0 @@
-import { test, expect, mock } from "bun:test";
-import {
-  clearArtifactInputParsers,
-  parse,
-  splitTextIntoContents,
-  validateSerializedArtifacts,
-} from "./input";
-
-// ---------------------------------------------------------------------------
-// Stub pdf-parse so the built-in PDF path in parseBufferInput can be tested
-// without a real PDF file.
-// ---------------------------------------------------------------------------
-mock.module("pdf-parse", () => ({
-  PDFParse: class {
-    constructor(_opts: unknown) {}
-    async getText() {
-      return { pages: [{ num: 1, text: "pdf text" }], text: "pdf text", total: 1 };
-    }
-    async getImage(_params?: unknown) {
-      return { pages: [], total: 0 };
-    }
-    async getInfo() {
-      return { Title: "Stub PDF" };
-    }
-    async destroy() {}
-  },
-}));
-
-test("validateSerializedArtifacts accepts a single artifact", () => {
-  const artifacts = validateSerializedArtifacts({
-    id: "a1",
-    type: "text",
-    contents: [{ text: "hello" }],
-  });
-
-  expect(artifacts).toHaveLength(1);
-  expect(artifacts[0]?.id).toBe("a1");
-});
-
-test("validateSerializedArtifacts rejects invalid artifacts", () => {
-  expect(() =>
-    validateSerializedArtifacts({
-      type: "text",
-      contents: [],
-    })
-  ).toThrow("Schema validation failed");
-});
-
-test("splitTextIntoContents splits paragraphs", () => {
-  const contents = splitTextIntoContents("one\n\nTwo\n\nthree");
-  expect(contents).toHaveLength(3);
-  expect(contents[1]?.text).toBe("Two");
-});
-
-test("parseInputToArtifacts builds text artifacts", async () => {
-  clearArtifactInputParsers();
-  const artifacts = await parse({
-    kind: "text",
-    text: "hello\n\nworld",
-    id: "t1",
-  });
-
-  expect(artifacts).toHaveLength(1);
-  expect(artifacts[0]?.id).toBe("t1");
-  expect(artifacts[0]?.contents).toHaveLength(2);
-});
-
-test("parse uses providers when available", async () => {
-  const providers = {
-    "application/pdf": async () => ({
-      id: "pdf-1",
-      type: "pdf" as const,
-      raw: async () => Buffer.from("pdf"),
-      contents: [{ text: "from-provider" }],
-    }),
-  };
-
-  const artifacts = await parse({
-    kind: "buffer",
-    buffer: Buffer.from("data"),
-    mimeType: "application/pdf",
-  }, { providers });
-
-  expect(artifacts[0]?.type).toBe("pdf");
-  expect(artifacts[0]?.contents[0]?.text).toBe("from-provider");
-});
-
-test("parse builds image artifacts", async () => {
-  clearArtifactInputParsers();
-  const buffer = Buffer.from([1, 2, 3]);
-  const artifacts = await parse({
-    kind: "buffer",
-    buffer,
-    mimeType: "image/png",
-    id: "img-1",
-  });
-
-  const media = artifacts[0]?.contents[0]?.media?.[0];
-  expect(artifacts[0]?.type).toBe("image");
-  expect(media?.type).toBe("image");
-  expect((media?.contents as Buffer).equals(buffer)).toBe(true);
-});
-
-test("parse uses parserConfig over providers", async () => {
-  const providers = {
-    "application/pdf": async () => ({
-      id: "from-provider",
-      type: "pdf" as const,
-      raw: async () => Buffer.from("pdf"),
-      contents: [{ text: "from-provider" }],
-    }),
-  };
-
-  const artifactJson = JSON.stringify([{
-    id: "from-parser",
-    type: "text",
-    contents: [{ text: "from-parser" }],
-  }]);
-  const parserConfig = {
-    "application/pdf": {
-      type: "command-stdin" as const,
-      command: `echo ${JSON.stringify(artifactJson)}`,
-    },
-  };
-
-  const artifacts = await parse(
-    {
-      kind: "buffer",
-      buffer: Buffer.from("data"),
-      mimeType: "application/pdf",
-    },
-    { providers, parserConfig }
-  );
-
-  expect(artifacts[0]?.id).toBe("from-parser");
-  expect(artifacts[0]?.contents[0]?.text).toBe("from-parser");
-});
-
-test("parse auto-detects JSON artifacts (buffer)", async () => {
-  clearArtifactInputParsers();
-  const serialized = [{ id: "j1", type: "text" as const, contents: [{ text: "json artifact" }] }];
-  const buffer = Buffer.from(JSON.stringify(serialized));
-
-  const artifacts = await parse({
-    kind: "buffer",
-    buffer,
-    mimeType: "application/json",
-  });
-
-  expect(artifacts).toHaveLength(1);
-  expect(artifacts[0]?.id).toBe("j1");
-  expect(artifacts[0]?.contents[0]?.text).toBe("json artifact");
-});
-
-test("parse throws for non-artifact JSON with no custom parser", async () => {
-  clearArtifactInputParsers();
-  const buffer = Buffer.from(JSON.stringify({ some: "object" }));
-
-  await expect(
-    parse({
-      kind: "buffer",
-      buffer,
-      mimeType: "application/json",
-    })
-  ).rejects.toThrow("not in SerializedArtifact format");
-});
-
-// ─── built-in PDF path ───────────────────────────────────────────────────────
-
-test("parse routes application/pdf to built-in parsePdf", async () => {
-  clearArtifactInputParsers();
-  const pdfBuffer = Buffer.from("%PDF-1.4 fake");
-
-  const artifacts = await parse({
-    kind: "buffer",
-    buffer: pdfBuffer,
-    mimeType: "application/pdf",
-  });
-
-  expect(artifacts).toHaveLength(1);
-  expect(artifacts[0]?.type).toBe("pdf");
-  expect(artifacts[0]?.contents[0]?.text).toBe("pdf text");
-});
-
-test("parse passes includeImages: false to parsePdf", async () => {
-  clearArtifactInputParsers();
-  const pdfBuffer = Buffer.from("%PDF-1.4 fake");
-
-  // With includeImages: false the result should still be a pdf artifact;
-  // we can't easily observe the absence of images here (the stub returns none
-  // anyway) but we verify the call succeeds and type is correct.
-  const artifacts = await parse(
-    {
-      kind: "buffer",
-      buffer: pdfBuffer,
-      mimeType: "application/pdf",
-    },
-    { includeImages: false }
-  );
-
-  expect(artifacts).toHaveLength(1);
-  expect(artifacts[0]?.type).toBe("pdf");
-});
-
-test("validateSerializedArtifacts accepts imageType field in media", () => {
-  const artifacts = validateSerializedArtifacts({
-    id: "a1",
-    type: "pdf",
-    contents: [
-      {
-        page: 1,
-        text: "page text",
-        media: [
-          { type: "image", base64: "abc123", imageType: "embedded" },
-          { type: "image", base64: "def456", imageType: "screenshot" },
-        ],
-      },
-    ],
-  });
-
-  expect(artifacts).toHaveLength(1);
-  expect(artifacts[0]?.contents[0]?.media).toHaveLength(2);
-  expect(artifacts[0]?.contents[0]?.media![0]?.imageType).toBe("embedded");
-  expect(artifacts[0]?.contents[0]?.media![1]?.imageType).toBe("screenshot");
-});
-
-test("validateSerializedArtifacts accepts media without imageType (optional field)", () => {
-  const artifacts = validateSerializedArtifacts({
-    id: "a1",
-    type: "pdf",
-    contents: [
-      {
-        page: 1,
-        text: "page text",
-        media: [{ type: "image", base64: "abc123" }],
-      },
-    ],
-  });
-
-  expect(artifacts).toHaveLength(1);
-  expect(artifacts[0]?.contents[0]?.media).toHaveLength(1);
-  expect(artifacts[0]?.contents[0]?.media![0]?.imageType).toBeUndefined();
-});

package/src/artifacts/input.ts

@@ -1,360 +0,0 @@
-import type { Artifact, ArtifactContent, ArtifactImage, ArtifactType } from "../types";
-import { createAjv, validateOrThrow } from "../validation/validator";
-import { defaultArtifactProviders, type ArtifactProviders } from "./providers";
-import type { ParsersConfig } from "../parsers/types";
-import { runParser } from "../parsers/runner";
-import type { ParsePdfOptions } from "../parsers/pdf";
-
-export type SerializedArtifactImage = Omit<ArtifactImage, "contents"> & {
-  contents?: never;
-};
-
-export type SerializedArtifactContent = Omit<ArtifactContent, "media"> & {
-  media?: SerializedArtifactImage[];
-};
-
-export type SerializedArtifact = Omit<Artifact, "raw" | "contents"> & {
-  contents: SerializedArtifactContent[];
-  raw?: never;
-};
-
-export type SerializedArtifacts = SerializedArtifact | SerializedArtifact[];
-
-export type ArtifactInput =
-  | { kind: "artifact-json"; data: unknown }
-  | { kind: "text"; text: string; id?: string }
-  | { kind: "file"; path: string; mimeType?: string; id?: string }
-  | { kind: "buffer"; buffer: Buffer; mimeType: string; id?: string };
-
-export type ArtifactInputParser = {
-  name: string;
-  canParse: (input: ArtifactInput) => boolean;
-  parse: (
-    input: ArtifactInput,
-    options?: { 
-      providers?: ArtifactProviders; 
-      parsers?: ParsersConfig; 
-      includeImages?: boolean;
-      screenshots?: boolean;
-      screenshotScale?: number;
-      screenshotWidth?: number;
-    }
-  ) => Promise<Artifact[]>;
-};
-
-const serializedArtifactImageSchema = {
-  type: "object",
-  required: ["type"],
-  properties: {
-    type: { const: "image" },
-    url: { type: "string", minLength: 1 },
-    base64: { type: "string", minLength: 1 },
-    text: { type: "string" },
-    x: { type: "number" },
-    y: { type: "number" },
-    width: { type: "number" },
-    height: { type: "number" },
-    imageType: { enum: ["embedded", "screenshot"] },
-  },
-  additionalProperties: false,
-  anyOf: [{ required: ["url"] }, { required: ["base64"] }],
-};
-
-const serializedArtifactContentSchema = {
-  type: "object",
-  properties: {
-    page: { type: "number" },
-    text: { type: "string" },
-    media: { type: "array", items: serializedArtifactImageSchema },
-  },
-  additionalProperties: false,
-  anyOf: [{ required: ["text"] }, { required: ["media"] }],
-};
-
-const serializedArtifactSchema = {
-  type: "object",
-  required: ["id", "type", "contents"],
-  properties: {
-    id: { type: "string", minLength: 1 },
-    type: { enum: ["text", "image", "pdf", "file"] as ArtifactType[] },
-    contents: { type: "array", items: serializedArtifactContentSchema },
-    metadata: { type: "object", additionalProperties: true },
-    tokens: { type: "number" },
-  },
-  additionalProperties: false,
-};
-
-const serializedArtifactsSchema = {
-  anyOf: [
-    serializedArtifactSchema,
-    { type: "array", items: serializedArtifactSchema },
-  ],
-};
-
-const inputParsers: ArtifactInputParser[] = [];
-
-export const registerArtifactInputParser = (parser: ArtifactInputParser) => {
-  inputParsers.push(parser);
-};
-
-export const clearArtifactInputParsers = () => {
-  inputParsers.length = 0;
-};
-
-export const validateSerializedArtifacts = (data: unknown): SerializedArtifact[] => {
-  const ajv = createAjv();
-  const parsed = validateOrThrow<SerializedArtifacts>(
-    ajv,
-    serializedArtifactsSchema,
-    data
-  );
-  return Array.isArray(parsed) ? parsed : [parsed];
-};
-
-export const hydrateSerializedArtifacts = (items: SerializedArtifact[]): Artifact[] => {
-  return items.map((item) => ({
-    ...item,
-    raw: async () => Buffer.from(JSON.stringify(item.contents ?? [])),
-  }));
-};
-
-export const parseSerializedArtifacts = (text: string): SerializedArtifact[] => {
-  const parsed = JSON.parse(text) as unknown;
-  return validateSerializedArtifacts(parsed);
-};
-
-export const splitTextIntoContents = (text: string): ArtifactContent[] => {
-  const blocks = text
-    .split(/\n\s*\n/g)
-    .map((block) => block.trim())
-    .filter((block) => block.length > 0);
-
-  if (blocks.length === 0) {
-    return [{ text }];
-  }
-
-  return blocks.map((block) => ({ text: block }));
-};
-
-const detectMimeType = async (path: string) => {
-  const file = Bun.file(path);
-  const type = file.type?.trim();
-  return type && type.length > 0 ? type : "application/octet-stream";
-};
-
-const bufferToTextArtifact = (buffer: Buffer, id?: string): Artifact => {
-  const text = buffer.toString();
-  return {
-    id: id ?? `artifact-${crypto.randomUUID()}`,
-    type: "text",
-    raw: async () => buffer,
-    contents: splitTextIntoContents(text),
-  };
-};
-
-const bufferToImageArtifact = (buffer: Buffer, id?: string): Artifact => {
-  return {
-    id: id ?? `artifact-${crypto.randomUUID()}`,
-    type: "image",
-    raw: async () => buffer,
-    contents: [
-      {
-        media: [{ type: "image", contents: buffer }],
-      },
-    ],
-  };
-};
-
-const parseBufferInput = async (
-  buffer: Buffer,
-  mimeType: string,
-  id?: string,
-  providers?: ArtifactProviders,
-  parsers?: ParsersConfig,
-  includeImages?: boolean,
-  screenshots?: boolean,
-  screenshotScale?: number,
-  screenshotWidth?: number,
-): Promise<Artifact[]> => {
-  // Resolution order:
-  // 1. parsers config (custom ParserDef) — if MIME type has a configured parser, use it
-  if (parsers) {
-    const parserDef = parsers[mimeType];
-    if (parserDef) {
-      return runParser(parserDef, { kind: "buffer", buffer }, mimeType);
-    }
-  }
-
-  // 2. providers registry (user-registered ArtifactProvider functions)
-  const registry = providers ?? defaultArtifactProviders;
-  const provider = registry[mimeType];
-  if (provider) {
-    return [await provider(buffer)];
-  }
-
-  // JSON auto-detection: if MIME is application/json, try to parse as SerializedArtifact[]
-  if (mimeType === "application/json") {
-    try {
-      const parsed = JSON.parse(buffer.toString()) as unknown;
-      const serialized = validateSerializedArtifacts(parsed);
-      return hydrateSerializedArtifacts(serialized);
-    } catch {
-      // If no custom parser is configured for application/json, throw clear error
-      throw new Error(
-        "Input is JSON but not in SerializedArtifact format. To parse arbitrary JSON files, configure a parser: struktur config parsers add --mime application/json ..."
-      );
-    }
-  }
-
-  // 3. Built-in PDF → pdf artifact
-  if (mimeType === "application/pdf") {
-    const { parsePdf } = await import("../parsers/pdf");
-    const pdfOptions: ParsePdfOptions = { 
-      includeImages, 
-      screenshots, 
-      screenshotScale, 
-      screenshotWidth 
-    };
-    return [await parsePdf(buffer, pdfOptions)];
-  }
-
-  // 4. Built-in text/* → text artifact
-  if (mimeType.startsWith("text/")) {
-    return [bufferToTextArtifact(buffer, id)];
-  }
-
-  // 5. Built-in image/* → image artifact
-  if (mimeType.startsWith("image/")) {
-    return [bufferToImageArtifact(buffer, id)];
-  }
-
-  throw new Error(`Unsupported MIME type: ${mimeType}`);
-};
-
-const artifactJsonParser: ArtifactInputParser = {
-  name: "artifact-json",
-  canParse: (input) => input.kind === "artifact-json",
-  parse: async (input) => {
-    if (input.kind !== "artifact-json") {
-      return [];
-    }
-    const serialized = validateSerializedArtifacts(input.data);
-    return hydrateSerializedArtifacts(serialized);
-  },
-};
-
-const textParser: ArtifactInputParser = {
-  name: "text",
-  canParse: (input) => input.kind === "text",
-  parse: async (input) => {
-    if (input.kind !== "text") {
-      return [];
-    }
-    const buffer = Buffer.from(input.text);
-    return [bufferToTextArtifact(buffer, input.id)];
-  },
-};
-
-const fileParser: ArtifactInputParser = {
-  name: "file",
-  canParse: (input) => input.kind === "file",
-  parse: async (input, options) => {
-    if (input.kind !== "file") {
-      return [];
-    }
-    const mimeType = input.mimeType ?? (await detectMimeType(input.path));
-
-    // JSON auto-detection: if MIME type is application/json, first try to validate as SerializedArtifact[]
-    if (mimeType === "application/json") {
-      const text = await Bun.file(input.path).text();
-      try {
-        const parsed = JSON.parse(text) as unknown;
-        const serialized = validateSerializedArtifacts(parsed);
-        return hydrateSerializedArtifacts(serialized);
-      } catch {
-        // Not valid artifact JSON — try custom parser or throw
-        if (options?.parsers) {
-          const parserDef = options.parsers[mimeType];
-          if (parserDef) {
-            return runParser(parserDef, { kind: "file", path: input.path }, mimeType);
-          }
-        }
-        throw new Error(
-          `File "${input.path}" is JSON but not in SerializedArtifact format. To parse arbitrary JSON files, configure a parser: struktur config parsers add --mime application/json ...`
-        );
-      }
-    }
-
-    const file = Bun.file(input.path);
-    const buffer = Buffer.from(await file.arrayBuffer());
-    return parseBufferInput(
-      buffer, 
-      mimeType, 
-      input.id, 
-      options?.providers, 
-      options?.parsers, 
-      options?.includeImages,
-      options?.screenshots,
-      options?.screenshotScale,
-      options?.screenshotWidth,
-    );
-  },
-};
-
-const bufferParser: ArtifactInputParser = {
-  name: "buffer",
-  canParse: (input) => input.kind === "buffer",
-  parse: async (input, options) => {
-    if (input.kind !== "buffer") {
-      return [];
-    }
-    return parseBufferInput(
-      input.buffer,
-      input.mimeType,
-      input.id,
-      options?.providers,
-      options?.parsers,
-      options?.includeImages,
-      options?.screenshots,
-      options?.screenshotScale,
-      options?.screenshotWidth,
-    );
-  },
-};
-
-export const parse = async (
-  input: ArtifactInput,
-  options?: { 
-    parsers?: ArtifactInputParser[]; 
-    providers?: ArtifactProviders; 
-    parserConfig?: ParsersConfig; 
-    includeImages?: boolean;
-    screenshots?: boolean;
-    screenshotScale?: number;
-    screenshotWidth?: number;
-  }
-): Promise<Artifact[]> => {
-  const parsers =
-    options?.parsers ??
-    [
-      ...inputParsers,
-      artifactJsonParser,
-      textParser,
-      fileParser,
-      bufferParser,
-    ];
-  const parser = parsers.find((candidate) => candidate.canParse(input));
-
-  if (!parser) {
-    throw new Error(`No artifact input parser available for ${input.kind}`);
-  }
-
-  return parser.parse(input, { 
-    providers: options?.providers, 
-    parsers: options?.parserConfig, 
-    includeImages: options?.includeImages,
-    screenshots: options?.screenshots,
-    screenshotScale: options?.screenshotScale,
-    screenshotWidth: options?.screenshotWidth,
-  });
-};

package/src/artifacts/providers.test.ts

@@ -1,19 +0,0 @@
-import { test, expect } from "bun:test";
-import { defaultArtifactProviders, type ArtifactProviders } from "./providers";
-
-test("defaultArtifactProviders is an object", () => {
-  expect(defaultArtifactProviders).toBeDefined();
-  expect(typeof defaultArtifactProviders).toBe("object");
-});
-
-test("ArtifactProviders type accepts MIME type keys", () => {
-  const providers: ArtifactProviders = {
-    "application/pdf": async (buffer) => ({
-      id: "pdf-1",
-      type: "pdf",
-      raw: async () => buffer,
-      contents: [{ page: 1, text: "test" }],
-    }),
-  };
-  expect(providers["application/pdf"]).toBeDefined();
-});

package/src/artifacts/providers.ts

@@ -1,7 +0,0 @@
-import type { Artifact } from "../types";
-
-export type ArtifactProvider = (buffer: Buffer) => Promise<Artifact>;
-
-export type ArtifactProviders = Record<string, ArtifactProvider>;
-
-export const defaultArtifactProviders: ArtifactProviders = {};

package/src/artifacts/urlToArtifact.test.ts

@@ -1,23 +0,0 @@
-import { test, expect } from "bun:test";
-import { urlToArtifact } from "./urlToArtifact";
-
-test("urlToArtifact fetches and builds artifact", async () => {
-  const originalFetch = globalThis.fetch;
-  globalThis.fetch = (async () =>
-    new Response(
-      JSON.stringify({
-        id: "a1",
-        type: "pdf",
-        contents: [{ text: "hello" }],
-      }),
-      { status: 200 }
-    )) as unknown as typeof fetch;
-
-  const artifact = await urlToArtifact("https://example.com/artifact");
-  const raw = await artifact.raw();
-
-  expect(artifact.id).toBe("a1");
-  expect(raw.toString()).toContain("hello");
-
-  globalThis.fetch = originalFetch;
-});

package/src/artifacts/urlToArtifact.ts

@@ -1,19 +0,0 @@
-import type { Artifact } from "../types";
-
-export const urlToArtifact = async (url: string): Promise<Artifact> => {
-  const response = await fetch(url);
-  if (!response.ok) {
-    throw new Error(`Failed to fetch artifact: ${response.status} ${response.statusText}`);
-  }
-
-  const data = (await response.json()) as Omit<Artifact, "raw"> & {
-    raw?: () => Promise<Buffer>;
-  };
-
-  return {
-    ...data,
-    raw:
-      data.raw ??
-      (async () => Buffer.from(JSON.stringify(data.contents ?? []))),
-  };
-};

package/src/auth/AGENTS.md

@@ -1,11 +0,0 @@
-Auth module
-
-- Purpose: persist and resolve provider API tokens and CLI defaults.
-- Key files: `tokens.ts`, `config.ts`.
-- Design: prefers macOS Keychain when available; otherwise uses `~/.config/struktur/tokens.json` with strict permissions.
-- Config store (`config.ts`): stores `defaultModel` (string), `aliases` (Record<string, string>), and `parsers` (ParsersConfig) in `~/.config/struktur/config.json`.
-- Alias API: `listAliases`, `getAlias`, `setAlias`, `deleteAlias`, `resolveAlias` (resolves alias → model spec, passthrough if not an alias).
-- Parsers config API: `listParsers`, `getParser`, `setParser`, `deleteParser`.
-  - `setParser` validates that `command-file` type parsers contain `FILE_PATH` in the command string.
-- Environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, OPENCODE_API_KEY, OPENROUTER_API_KEY.
-- Tests: `tokens.test.ts`.