@struktur/sdk 2.1.1 → 2.2.0

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`.

package/src/auth/config.test.ts

@@ -1,132 +0,0 @@
-import { test, expect } from "bun:test";
-import path from "node:path";
-import os from "node:os";
-import { rm } from "node:fs/promises";
-import {
-  listParsers,
-  getParser,
-  setParser,
-  deleteParser,
-} from "./config";
-
-const makeTempDir = () => {
-  const suffix = Math.random().toString(16).slice(2);
-  return path.join(os.tmpdir(), `struktur-test-${suffix}`);
-};
-
-test("listParsers returns empty object when no parsers configured", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-
-  try {
-    const parsers = await listParsers();
-    expect(parsers).toEqual({});
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});
-
-test("setParser stores an npm parser", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-
-  try {
-    await setParser("application/pdf", { type: "npm", package: "my-pdf-parser" });
-    const parser = await getParser("application/pdf");
-    expect(parser).toEqual({ type: "npm", package: "my-pdf-parser" });
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});
-
-test("setParser stores a command-file parser", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-
-  try {
-    await setParser("application/pdf", {
-      type: "command-file",
-      command: "my-cmd FILE_PATH output",
-    });
-    const parser = await getParser("application/pdf");
-    expect(parser).toEqual({ type: "command-file", command: "my-cmd FILE_PATH output" });
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});
-
-test("setParser rejects command-file without FILE_PATH placeholder", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-
-  try {
-    await expect(
-      setParser("application/pdf", { type: "command-file", command: "my-cmd --input" })
-    ).rejects.toThrow("FILE_PATH");
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});
-
-test("setParser stores a command-stdin parser", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-
-  try {
-    await setParser("text/csv", { type: "command-stdin", command: "csv-to-json" });
-    const parser = await getParser("text/csv");
-    expect(parser).toEqual({ type: "command-stdin", command: "csv-to-json" });
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});
-
-test("listParsers returns all stored parsers", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-
-  try {
-    await setParser("application/pdf", { type: "npm", package: "pdf-parser" });
-    await setParser("text/csv", { type: "command-stdin", command: "csv-parse" });
-    const parsers = await listParsers();
-    expect(parsers["application/pdf"]).toEqual({ type: "npm", package: "pdf-parser" });
-    expect(parsers["text/csv"]).toEqual({ type: "command-stdin", command: "csv-parse" });
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});
-
-test("deleteParser removes stored parser and returns true", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-
-  try {
-    await setParser("application/pdf", { type: "npm", package: "pdf-parser" });
-    const deleted = await deleteParser("application/pdf");
-    expect(deleted).toBe(true);
-    const parser = await getParser("application/pdf");
-    expect(parser).toBeUndefined();
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});
-
-test("deleteParser returns false when parser does not exist", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-
-  try {
-    const deleted = await deleteParser("application/pdf");
-    expect(deleted).toBe(false);
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});

package/src/auth/config.ts

@@ -1,186 +0,0 @@
-import path from "node:path";
-import os from "node:os";
-import { chmod, mkdir } from "node:fs/promises";
-import type { ParserDef, ParsersConfig } from "@struktur/sdk";
-
-type TelemetryConfig = {
-  enabled: boolean;
-  provider: string;
-  url?: string;
-  apiKey?: string;
-  projectName?: string;
-  publicKey?: string; // For Langfuse
-  secretKey?: string; // For Langfuse
-  baseUrl?: string; // For Langfuse
-  sampleRate?: number;
-};
-
-type ConfigStore = {
-  version: 1;
-  defaultModel?: string;
-  aliases?: Record<string, string>;
-  parsers?: ParsersConfig;
-  telemetry?: TelemetryConfig;
-};
-
-const CONFIG_DIR_ENV = "STRUKTUR_CONFIG_DIR";
-
-const resolveConfigDir = () => {
-  return process.env[CONFIG_DIR_ENV] ?? path.join(os.homedir(), ".config", "struktur");
-};
-
-const resolveConfigPath = () => path.join(resolveConfigDir(), "config.json");
-
-const emptyStore = (): ConfigStore => ({ version: 1 });
-
-const readConfigStore = async (): Promise<ConfigStore> => {
-  const configPath = resolveConfigPath();
-  const exists = await Bun.file(configPath).exists();
-  if (!exists) {
-    return emptyStore();
-  }
-  const raw = await Bun.file(configPath).text();
-  const parsed = JSON.parse(raw) as ConfigStore;
-  if (!parsed || parsed.version !== 1) {
-    return emptyStore();
-  }
-  return parsed;
-};
-
-const writeConfigStore = async (store: ConfigStore) => {
-  const configDir = resolveConfigDir();
-  const configPath = resolveConfigPath();
-  await mkdir(configDir, { recursive: true, mode: 0o700 });
-  await Bun.write(configPath, JSON.stringify(store, null, 2));
-  await chmod(configDir, 0o700);
-  await chmod(configPath, 0o600);
-};
-
-export const getDefaultModel = async () => {
-  const store = await readConfigStore();
-  return store.defaultModel;
-};
-
-export const setDefaultModel = async (model: string) => {
-  const store = await readConfigStore();
-  store.defaultModel = model;
-  await writeConfigStore(store);
-  return model;
-};
-
-// --- Alias management ---
-
-export const listAliases = async (): Promise<Record<string, string>> => {
-  const store = await readConfigStore();
-  return store.aliases ?? {};
-};
-
-export const getAlias = async (alias: string): Promise<string | undefined> => {
-  const store = await readConfigStore();
-  return store.aliases?.[alias];
-};
-
-export const setAlias = async (alias: string, model: string): Promise<string> => {
-  const store = await readConfigStore();
-  store.aliases ??= {};
-  store.aliases[alias] = model;
-  await writeConfigStore(store);
-  return model;
-};
-
-export const deleteAlias = async (alias: string): Promise<boolean> => {
-  const store = await readConfigStore();
-  if (!store.aliases?.[alias]) {
-    return false;
-  }
-  delete store.aliases[alias];
-  await writeConfigStore(store);
-  return true;
-};
-
-/**
- * Resolve a model spec: if it matches a stored alias, return the aliased model string.
- * Otherwise return the original spec unchanged.
- */
-export const resolveAlias = async (modelSpec: string): Promise<string> => {
-  const aliases = await listAliases();
-  return aliases[modelSpec] ?? modelSpec;
-};
-
-// --- Parser config management ---
-
-export const listParsers = async (): Promise<ParsersConfig> => {
-  const store = await readConfigStore();
-  return store.parsers ?? {};
-};
-
-export const getParser = async (mimeType: string): Promise<ParserDef | undefined> => {
-  const store = await readConfigStore();
-  return store.parsers?.[mimeType];
-};
-
-export const setParser = async (mimeType: string, def: ParserDef): Promise<void> => {
-  if (def.type === "command-file" && !def.command.includes("FILE_PATH")) {
-    throw new Error(
-      `command-file parser must contain FILE_PATH placeholder in the command string. Got: "${def.command}"`
-    );
-  }
-  const store = await readConfigStore();
-  store.parsers ??= {};
-  store.parsers[mimeType] = def;
-  await writeConfigStore(store);
-};
-
-export const deleteParser = async (mimeType: string): Promise<boolean> => {
-  const store = await readConfigStore();
-  if (!store.parsers?.[mimeType]) {
-    return false;
-  }
-  delete store.parsers[mimeType];
-  await writeConfigStore(store);
-  return true;
-};
-
-// --- Telemetry config management ---
-
-export const getTelemetryConfig = async (): Promise<TelemetryConfig | undefined> => {
-  const store = await readConfigStore();
-  return store.telemetry;
-};
-
-export const setTelemetryConfig = async (config: TelemetryConfig): Promise<void> => {
-  const store = await readConfigStore();
-  store.telemetry = config;
-  await writeConfigStore(store);
-};
-
-export const enableTelemetry = async (
-  provider: string,
-  options: Omit<TelemetryConfig, "enabled" | "provider">
-): Promise<void> => {
-  const store = await readConfigStore();
-  store.telemetry = {
-    enabled: true,
-    provider,
-    ...options,
-  };
-  await writeConfigStore(store);
-};
-
-export const disableTelemetry = async (): Promise<void> => {
-  const store = await readConfigStore();
-  if (store.telemetry) {
-    store.telemetry.enabled = false;
-  }
-  await writeConfigStore(store);
-};
-
-export const deleteTelemetryConfig = async (): Promise<boolean> => {
-  const store = await readConfigStore();
-  if (!store.telemetry) {
-    return false;
-  }
-  delete store.telemetry;
-  await writeConfigStore(store);
-  return true;
-};

package/src/auth/tokens.test.ts

@@ -1,58 +0,0 @@
-import { test, expect } from "bun:test";
-import path from "node:path";
-import os from "node:os";
-import { rm } from "node:fs/promises";
-import {
-  deleteProviderToken,
-  getProviderTokenOrThrow,
-  listStoredProviders,
-  resolveProviderToken,
-  setProviderToken,
-} from "./tokens";
-
-const makeTempDir = () => {
-  const suffix = Math.random().toString(16).slice(2);
-  return path.join(os.tmpdir(), `struktur-test-${suffix}`);
-};
-
-test("setProviderToken stores token in file when keychain disabled", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-  process.env.STRUKTUR_DISABLE_KEYCHAIN = "1";
-
-  try {
-    const storage = await setProviderToken("openai", "sk-test", "auto");
-    expect(storage).toBe("file");
-
-    const resolved = await resolveProviderToken("openai");
-    expect(resolved).toBe("sk-test");
-
-    const listed = await listStoredProviders();
-    expect(listed).toEqual([{ provider: "openai", storage: "file" }]);
-
-    const token = await getProviderTokenOrThrow("openai");
-    expect(token).toBe("sk-test");
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    delete process.env.STRUKTUR_DISABLE_KEYCHAIN;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});
-
-test("deleteProviderToken removes stored token", async () => {
-  const tempDir = makeTempDir();
-  process.env.STRUKTUR_CONFIG_DIR = tempDir;
-  process.env.STRUKTUR_DISABLE_KEYCHAIN = "1";
-
-  try {
-    await setProviderToken("anthropic", "sk-test", "auto");
-    const deleted = await deleteProviderToken("anthropic");
-    expect(deleted).toBe(true);
-    const resolved = await resolveProviderToken("anthropic");
-    expect(resolved).toBeUndefined();
-  } finally {
-    delete process.env.STRUKTUR_CONFIG_DIR;
-    delete process.env.STRUKTUR_DISABLE_KEYCHAIN;
-    await rm(tempDir, { recursive: true, force: true });
-  }
-});

package/src/auth/tokens.ts

@@ -1,229 +0,0 @@
-import path from "node:path";
-import os from "node:os";
-import { chmod, mkdir } from "node:fs/promises";
-
-export type TokenStorageType = "auto" | "keychain" | "file";
-
-export type TokenEntry = {
-  storage: "keychain" | "file";
-  token?: string;
-  account?: string;
-  service?: string;
-};
-
-type TokenStore = {
-  version: 1;
-  providers: Record<string, TokenEntry>;
-};
-
-const CONFIG_DIR_ENV = "STRUKTUR_CONFIG_DIR";
-const DISABLE_KEYCHAIN_ENV = "STRUKTUR_DISABLE_KEYCHAIN";
-const SERVICE_ENV = "STRUKTUR_KEYCHAIN_SERVICE";
-const DEFAULT_SERVICE = "struktur";
-
-const resolveConfigDir = () => {
-  return process.env[CONFIG_DIR_ENV] ?? path.join(os.homedir(), ".config", "struktur");
-};
-
-const resolveTokensPath = () => path.join(resolveConfigDir(), "tokens.json");
-
-const emptyStore = (): TokenStore => ({ version: 1, providers: {} });
-
-const readTokenStore = async (): Promise<TokenStore> => {
-  const tokensPath = resolveTokensPath();
-  const exists = await Bun.file(tokensPath).exists();
-  if (!exists) {
-    return emptyStore();
-  }
-  const raw = await Bun.file(tokensPath).text();
-  const parsed = JSON.parse(raw) as TokenStore;
-  if (!parsed || parsed.version !== 1 || typeof parsed.providers !== "object") {
-    return emptyStore();
-  }
-  return parsed;
-};
-
-const writeTokenStore = async (store: TokenStore) => {
-  const configDir = resolveConfigDir();
-  const tokensPath = resolveTokensPath();
-  await mkdir(configDir, { recursive: true, mode: 0o700 });
-  await Bun.write(tokensPath, JSON.stringify(store, null, 2));
-  await chmod(configDir, 0o700);
-  await chmod(tokensPath, 0o600);
-};
-
-const isKeychainAvailable = async () => {
-  if (process.env[DISABLE_KEYCHAIN_ENV]) {
-    return false;
-  }
-  if (process.platform !== "darwin") {
-    return false;
-  }
-  return await Bun.file("/usr/bin/security").exists();
-};
-
-const keychainService = () => process.env[SERVICE_ENV] ?? DEFAULT_SERVICE;
-
-const runSecurity = async (args: string[]) => {
-  const proc = Bun.spawn({
-    cmd: ["/usr/bin/security", ...args],
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const stdout = await new Response(proc.stdout).text();
-  const stderr = await new Response(proc.stderr).text();
-  const exitCode = await proc.exited;
-  if (exitCode !== 0) {
-    const message = stderr.trim() || `security exited with ${exitCode}`;
-    throw new Error(message);
-  }
-  return stdout;
-};
-
-const writeKeychainToken = async (provider: string, token: string) => {
-  await runSecurity([
-    "add-generic-password",
-    "-a",
-    provider,
-    "-s",
-    keychainService(),
-    "-w",
-    token,
-    "-U",
-  ]);
-};
-
-const readKeychainToken = async (provider: string) => {
-  const output = await runSecurity([
-    "find-generic-password",
-    "-a",
-    provider,
-    "-s",
-    keychainService(),
-    "-w",
-  ]);
-  return output.trim();
-};
-
-const deleteKeychainToken = async (provider: string) => {
-  await runSecurity([
-    "delete-generic-password",
-    "-a",
-    provider,
-    "-s",
-    keychainService(),
-  ]);
-};
-
-export const listStoredProviders = async () => {
-  const store = await readTokenStore();
-  return Object.entries(store.providers).map(([provider, entry]) => ({
-    provider,
-    storage: entry.storage,
-  }));
-};
-
-export const setProviderToken = async (
-  provider: string,
-  token: string,
-  storage: TokenStorageType = "auto"
-) => {
-  const store = await readTokenStore();
-  let resolvedStorage: TokenEntry["storage"] = "file";
-
-  if (storage === "keychain") {
-    if (!(await isKeychainAvailable())) {
-      throw new Error("Keychain is not available on this platform.");
-    }
-    resolvedStorage = "keychain";
-  } else if (storage === "auto") {
-    resolvedStorage = (await isKeychainAvailable()) ? "keychain" : "file";
-  }
-
-  if (resolvedStorage === "keychain") {
-    await writeKeychainToken(provider, token);
-    store.providers[provider] = {
-      storage: "keychain",
-      account: provider,
-      service: keychainService(),
-    };
-  } else {
-    store.providers[provider] = {
-      storage: "file",
-      token,
-    };
-  }
-
-  await writeTokenStore(store);
-  return resolvedStorage;
-};
-
-export const deleteProviderToken = async (provider: string) => {
-  const store = await readTokenStore();
-  const entry = store.providers[provider];
-  if (!entry) {
-    return false;
-  }
-
-  if (entry.storage === "keychain") {
-    try {
-      await deleteKeychainToken(provider);
-    } catch {
-      // ignore errors for missing keychain items
-    }
-  }
-
-  delete store.providers[provider];
-  await writeTokenStore(store);
-  return true;
-};
-
-export const resolveProviderToken = async (provider: string) => {
-  const store = await readTokenStore();
-  const entry = store.providers[provider];
-  if (!entry) {
-    return undefined;
-  }
-
-  if (entry.storage === "file") {
-    return entry.token;
-  }
-
-  try {
-    return await readKeychainToken(provider);
-  } catch {
-    return undefined;
-  }
-};
-
-export const getProviderTokenOrThrow = async (provider: string) => {
-  const token = await resolveProviderToken(provider);
-  if (!token) {
-    throw new Error(`No token stored for provider: ${provider}`);
-  }
-  return token;
-};
-
-export const resolveProviderEnvVar = (provider: string) => {
-  switch (provider) {
-    case "openai":
-      return "OPENAI_API_KEY";
-    case "anthropic":
-      return "ANTHROPIC_API_KEY";
-    case "google":
-      return "GOOGLE_GENERATIVE_AI_API_KEY";
-    case "opencode":
-      return "OPENCODE_API_KEY";
-    case "openrouter":
-      return "OPENROUTER_API_KEY";
-    default:
-      return undefined;
-  }
-};
-
-export const maskToken = (token: string) => {
-  if (token.length <= 8) {
-    return "********";
-  }
-  return `${token.slice(0, 4)}...${token.slice(-4)}`;
-};

package/src/chunking/AGENTS.md

@@ -1,11 +0,0 @@
-Chunking module
-
-- Purpose: split and batch artifacts based on token and image limits.
-- Key files: `ArtifactSplitter.ts`, `ArtifactBatcher.ts`.
-- Design: split large artifact contents into parts, then batch parts to fit limits.
-- Tests: `ArtifactSplitter.test.ts`, `ArtifactBatcher.test.ts`.
-
-IMPORTANT: When modifying chunking/batching logic, you MUST also update the client-side
-JavaScript implementation in `src/cli.ts` (`generateArtifactViewerHtml`) to keep the
-artifact viewer's chunking visualization in sync. The viewer includes a version stamp
-to help users verify they're comparing the correct algorithm version.

package/src/chunking/ArtifactBatcher.test.ts

@@ -1,22 +0,0 @@
-import { test, expect } from "bun:test";
-import type { Artifact } from "../types";
-import { batchArtifacts } from "./ArtifactBatcher";
-
-const makeArtifact = (id: string, text: string): Artifact => ({
-  id,
-  type: "text",
-  raw: async () => Buffer.from(text),
-  contents: [{ text }],
-});
-
-test("batchArtifacts respects maxTokens", () => {
-  const artifacts = [
-    makeArtifact("a1", "abcdefgh"),
-    makeArtifact("a2", "abcdefgh"),
-  ];
-
-  const batches = batchArtifacts(artifacts, { maxTokens: 2 });
-  expect(batches.length).toBe(2);
-  expect(batches[0]?.length).toBe(1);
-  expect(batches[1]?.length).toBe(1);
-});