@levelcode/sdk 0.2.3 → 0.2.5

package/dist/common/src/templates/initial-agents-dir/types/util-types.d.ts

@@ -1,128 +0,0 @@
-export type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
-export type JSONObject = {
-    [key: string]: JSONValue;
-};
-export type JSONArray = JSONValue[];
-/**
- * JSON Schema definition (for prompt schema or output schema)
- */
-export type JsonSchema = {
-    type?: 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null' | 'integer';
-    description?: string;
-    properties?: Record<string, JsonSchema | boolean>;
-    required?: string[];
-    enum?: Array<string | number | boolean | null>;
-    [k: string]: unknown;
-};
-export type JsonObjectSchema = JsonSchema & {
-    type: 'object';
-};
-export type DataContent = string | Uint8Array | ArrayBuffer | Buffer;
-export type ProviderMetadata = Record<string, Record<string, JSONValue>>;
-export type TextPart = {
-    type: 'text';
-    text: string;
-    providerOptions?: ProviderMetadata;
-};
-export type ImagePart = {
-    type: 'image';
-    image: DataContent;
-    mediaType?: string;
-    providerOptions?: ProviderMetadata;
-};
-export type FilePart = {
-    type: 'file';
-    data: DataContent;
-    filename?: string;
-    mediaType: string;
-    providerOptions?: ProviderMetadata;
-};
-export type ReasoningPart = {
-    type: 'reasoning';
-    text: string;
-    providerOptions?: ProviderMetadata;
-};
-export type ToolCallPart = {
-    type: 'tool-call';
-    toolCallId: string;
-    toolName: string;
-    input: Record<string, unknown>;
-    providerOptions?: ProviderMetadata;
-    providerExecuted?: boolean;
-};
-export type ToolResultOutput = {
-    type: 'json';
-    value: JSONValue;
-} | {
-    type: 'media';
-    data: string;
-    mediaType: string;
-};
-export type AuxiliaryMessageData = {
-    providerOptions?: ProviderMetadata;
-    tags?: string[];
-    /** @deprecated Use tags instead. */
-    timeToLive?: 'agentStep' | 'userPrompt';
-    /** @deprecated Use tags instead. */
-    keepDuringTruncation?: boolean;
-    /** @deprecated Use tags instead. */
-    keepLastTags?: string[];
-};
-export type SystemMessage = {
-    role: 'system';
-    content: TextPart[];
-} & AuxiliaryMessageData;
-export type UserMessage = {
-    role: 'user';
-    content: (TextPart | ImagePart | FilePart)[];
-} & AuxiliaryMessageData;
-export type AssistantMessage = {
-    role: 'assistant';
-    content: (TextPart | ReasoningPart | ToolCallPart)[];
-} & AuxiliaryMessageData;
-export type ToolMessage = {
-    role: 'tool';
-    toolCallId: string;
-    toolName: string;
-    content: ToolResultOutput[];
-} & AuxiliaryMessageData;
-export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
-/**
- * MCP server configuration for stdio-based servers.
- *
- * Environment variables in `env` can be:
- * - A plain string value (hardcoded, e.g., `'production'`)
- * - A `$VAR_NAME` reference to read from local environment (e.g., `'$NOTION_TOKEN'`)
- *
- * The `$VAR_NAME` syntax reads from `process.env.VAR_NAME` at agent load time.
- * This keeps secrets out of your agent definitions - store them in `.env.local` instead.
- *
- * @example
- * ```typescript
- * env: {
- *   // Read NOTION_TOKEN from local .env file
- *   NOTION_TOKEN: '$NOTION_TOKEN',
- *   // Read MY_API_KEY from local env, pass as API_KEY to MCP server
- *   API_KEY: '$MY_API_KEY',
- *   // Hardcoded value (non-secret)
- *   NODE_ENV: 'production',
- * }
- * ```
- */
-export type MCPConfig = {
-    type?: 'stdio';
-    command: string;
-    args?: string[];
-    env?: Record<string, string>;
-} | {
-    type?: 'http' | 'sse';
-    url: string;
-    params?: Record<string, string>;
-    headers?: Record<string, string>;
-};
-export interface Logger {
-    debug: (data: any, msg?: string) => void;
-    info: (data: any, msg?: string) => void;
-    warn: (data: any, msg?: string) => void;
-    error: (data: any, msg?: string) => void;
-}

package/dist/common/src/testing/errors.d.ts

@@ -1,14 +0,0 @@
-/**
- * Shared error helper utilities for tests.
- * These provide typed ways to create errors with additional properties
- * like `code` (for Node.js filesystem errors) and `constraint` (for Postgres errors).
- */
-export interface NodeError extends Error {
-    code?: string;
-}
-export interface PostgresError extends Error {
-    code: string;
-    constraint?: string;
-}
-export declare const createNodeError: (message: string, code: string) => NodeError;
-export declare const createPostgresError: (message: string, code: string, constraint?: string) => PostgresError;

package/dist/common/src/testing/mock-modules.d.ts

@@ -1,11 +0,0 @@
-export type MockResult = {
-    clear: () => void;
-};
-/**
- *
- * @param modulePath - the path starting from this files' path.
- * @param renderMocks - function to generate mocks (by their named or default exports)
- * @returns an object
- */
-export declare function mockModule(modulePath: string, renderMocks: () => Record<string, any>): Promise<MockResult>;
-export declare const clearMockedModules: () => void;

package/dist/common/src/testing/mock-types.d.ts

@@ -1,97 +0,0 @@
-/**
- * Shared mock types for testing.
- *
- * This module provides common mock types and factory functions that are
- * frequently used across test files. Using these shared types ensures
- * consistency and reduces duplication in test code.
- *
- * @example
- * ```typescript
- * import {
- *   createMockLogger,
- *   type MockUserInfo,
- *   type MockCreditResult,
- * } from '@levelcode/common/testing/mock-types'
- *
- * const logger = createMockLogger()
- * const userInfo: MockUserInfo = { id: 'user-123' }
- * ```
- */
-import { mock } from 'bun:test';
-import type { Logger } from '../types/contracts/logger';
-/**
- * Mock user info returned by API key lookup functions.
- * Contains the minimal user identification data needed for testing.
- */
-export interface MockUserInfo {
-    id: string;
-}
-/**
- * Mock result from credit consumption operations.
- * Used when testing billing-related functionality.
- */
-export interface MockCreditResult {
-    success: boolean;
-    value: {
-        chargedToOrganization: boolean;
-    };
-}
-/**
- * Mock file stat result for filesystem operations.
- * Provides typed methods for checking file type.
- */
-export interface MockStatResult {
-    isDirectory: () => boolean;
-    isFile: () => boolean;
-}
-/**
- * Typed mock logger where each method is a Bun test mock.
- * Useful for verifying that specific log methods were called.
- */
-export type MockLogger = {
-    [K in keyof Logger]: ReturnType<typeof mock> & Logger[K];
-};
-/**
- * Creates a mock logger with all methods as Bun test mocks.
- * Each method can be inspected for calls using mock.calls.
- *
- * @example
- * ```typescript
- * const logger = createMockLogger()
- * someFunction({ logger })
- * expect(logger.error.mock.calls.length).toBe(1)
- * ```
- */
-export declare function createMockLogger(): MockLogger;
-/**
- * Creates a mock stat result for filesystem testing.
- *
- * @param options - Configure whether the mock represents a directory or file
- * @returns A MockStatResult with the specified behavior
- *
- * @example
- * ```typescript
- * const dirStat = createMockStatResult({ isDirectory: true })
- * const fileStat = createMockStatResult({ isFile: true })
- * ```
- */
-export declare function createMockStatResult(options: {
-    isDirectory?: boolean;
-    isFile?: boolean;
-}): MockStatResult;
-/**
- * Creates a mock credit result for billing-related tests.
- *
- * @param options - Configure the success state and organization charging
- * @returns A MockCreditResult with the specified values
- *
- * @example
- * ```typescript
- * const successResult = createMockCreditResult({ success: true })
- * const orgResult = createMockCreditResult({ success: true, chargedToOrganization: true })
- * ```
- */
-export declare function createMockCreditResult(options?: {
-    success?: boolean;
-    chargedToOrganization?: boolean;
-}): MockCreditResult;

package/dist/common/src/testing/mocks/analytics.d.ts

@@ -1,182 +0,0 @@
-/**
- * Typed analytics mock factory for testing.
- *
- * Provides type-safe mocks for analytics functions used throughout the codebase.
- * Helps avoid the need for `as any` casts when mocking analytics in tests.
- *
- * @example
- * ```typescript
- * import { createMockAnalytics, setupAnalyticsMocks } from '@levelcode/common/testing/mocks/analytics'
- *
- * // Option 1: Create mock object
- * const analytics = createMockAnalytics()
- * someFunction({ trackEvent: analytics.trackEvent })
- *
- * // Option 2: Setup spies on actual module
- * const spies = setupAnalyticsMocks()
- * await runTest()
- * expect(spies.trackEvent).toHaveBeenCalledWith('event_name', { prop: 'value' })
- * spies.restore()
- * ```
- */
-import { spyOn } from 'bun:test';
-import type { Mock } from 'bun:test';
-/**
- * Properties that can be tracked with an event.
- */
-export type EventProperties = Record<string, unknown>;
-/**
- * Signature for the trackEvent function.
- */
-export type TrackEventFn = (eventName: string, properties?: EventProperties) => void;
-/**
- * Signature for the flushAnalytics function.
- */
-export type FlushAnalyticsFn = () => Promise<void>;
-/**
- * Signature for the identifyUser function.
- */
-export type IdentifyUserFn = (userId: string, traits?: Record<string, unknown>) => void;
-/**
- * Interface for the complete mock analytics object.
- */
-export interface MockAnalytics {
-    /** Track a named event with optional properties */
-    trackEvent: Mock<TrackEventFn>;
-    /** Flush pending analytics events */
-    flushAnalytics: Mock<FlushAnalyticsFn>;
-    /** Identify a user with optional traits */
-    identifyUser: Mock<IdentifyUserFn>;
-}
-/**
- * Tracked event entry for inspection.
- */
-export interface TrackedEvent {
-    name: string;
-    properties?: EventProperties;
-    timestamp: Date;
-}
-/**
- * Options for creating mock analytics.
- */
-export interface CreateMockAnalyticsOptions {
-    /**
-     * Whether to capture tracked events for later inspection.
-     * @default false
-     */
-    captureEvents?: boolean;
-}
-/**
- * Creates a type-safe mock analytics object for testing.
- *
- * @param options - Configuration options
- * @returns A mock analytics object with all methods as tracked mocks
- *
- * @example
- * ```typescript
- * const analytics = createMockAnalytics()
- *
- * // Pass to function under test
- * await processPayment({ analytics })
- *
- * // Verify events were tracked
- * expect(analytics.trackEvent).toHaveBeenCalledWith('payment_processed', {
- *   amount: 100,
- *   currency: 'USD',
- * })
- * ```
- */
-export declare function createMockAnalytics(options?: CreateMockAnalyticsOptions): MockAnalytics;
-/**
- * Result of creating mock analytics with event capture.
- */
-export interface MockAnalyticsWithCapture {
-    /** The mock analytics object */
-    analytics: MockAnalytics;
-    /** Array of all tracked events */
-    events: TrackedEvent[];
-    /** Clear all captured events */
-    clearEvents: () => void;
-    /** Get events by name */
-    getEventsByName: (name: string) => TrackedEvent[];
-    /** Check if an event was tracked */
-    hasEvent: (name: string) => boolean;
-    /** Get the last event tracked */
-    getLastEvent: () => TrackedEvent | undefined;
-}
-/**
- * Creates mock analytics that captures all tracked events for inspection.
- *
- * @returns An object containing the analytics mock and utilities for inspection
- *
- * @example
- * ```typescript
- * const { analytics, events, getEventsByName } = createMockAnalyticsWithCapture()
- *
- * await runUserFlow({ analytics })
- *
- * // Check events were tracked in order
- * expect(events.map(e => e.name)).toEqual([
- *   'flow_started',
- *   'step_completed',
- *   'flow_finished',
- * ])
- *
- * // Check specific event properties
- * const completionEvents = getEventsByName('step_completed')
- * expect(completionEvents[0].properties).toMatchObject({ stepId: 'step1' })
- * ```
- */
-export declare function createMockAnalyticsWithCapture(): MockAnalyticsWithCapture;
-/**
- * Result of setting up analytics spies on the actual module.
- */
-export interface AnalyticsSpies {
-    /** Spy on trackEvent */
-    trackEvent: ReturnType<typeof spyOn>;
-    /** Spy on flushAnalytics */
-    flushAnalytics: ReturnType<typeof spyOn>;
-    /** Restore all spies */
-    restore: () => void;
-    /** Clear all spy call history */
-    clear: () => void;
-}
-/**
- * Sets up spies on the analytics module.
- * Use this when you need to spy on the actual module rather than inject a mock.
- *
- * @param analyticsModule - The analytics module to spy on
- * @returns Object containing the spies and cleanup utilities
- *
- * @example
- * ```typescript
- * import * as analytics from '@levelcode/common/analytics'
- *
- * describe('my test', () => {
- *   let analyticsSpy: AnalyticsSpies
- *
- *   beforeEach(() => {
- *     analyticsSpy = setupAnalyticsMocks(analytics)
- *   })
- *
- *   afterEach(() => {
- *     analyticsSpy.restore()
- *   })
- *
- *   it('tracks the event', async () => {
- *     await doSomething()
- *     expect(analyticsSpy.trackEvent).toHaveBeenCalledWith('something_done')
- *   })
- * })
- * ```
- */
-export declare function setupAnalyticsMocks(analyticsModule: {
-    trackEvent: TrackEventFn;
-    flushAnalytics: FlushAnalyticsFn;
-}): AnalyticsSpies;
-/**
- * Restores all mock methods on an analytics object.
- *
- * @param analytics - The mock analytics to restore
- */
-export declare function restoreMockAnalytics(analytics: MockAnalytics): void;

package/dist/common/src/testing/mocks/child-process.d.ts

@@ -1,29 +0,0 @@
-/** Typed child process mock for testing code that spawns processes. */
-import { EventEmitter } from 'events';
-import type { Mock } from 'bun:test';
-import type { ChildProcess } from 'child_process';
-/** Mock child process with typed stdout/stderr EventEmitters. */
-export interface MockChildProcess extends EventEmitter {
-    stdout: EventEmitter;
-    stderr: EventEmitter;
-    pid: number;
-    killed: boolean;
-    kill: Mock<(signal?: string) => boolean>;
-}
-/** Creates a typed mock child process with EventEmitter-based stdout/stderr. */
-export declare function createMockChildProcess(): MockChildProcess;
-/** Result type for code search tool output. */
-export interface CodeSearchResult {
-    stdout?: string;
-    stderr?: string;
-    message?: string;
-    errorMessage?: string;
-}
-/** Typed accessor for code search result value. */
-export declare function asCodeSearchResult(result: unknown): CodeSearchResult;
-/** Creates a mock spawn function that returns the provided mock process. */
-export declare function createMockSpawn(mockProcess: MockChildProcess): Mock<(command: string, args: string[], options?: object) => ChildProcess>;
-/** Helper to create ripgrep JSON match output. */
-export declare function createRgJsonMatch(filePath: string, lineNumber: number, lineText: string): string;
-/** Helper to create ripgrep JSON context output (for -A, -B, -C flags). */
-export declare function createRgJsonContext(filePath: string, lineNumber: number, lineText: string): string;

package/dist/common/src/testing/mocks/crypto.d.ts

@@ -1,159 +0,0 @@
-/**
- * Typed crypto mock factory for testing.
- *
- * Provides type-safe mocks for crypto functions, particularly randomUUID.
- * Makes tests deterministic by returning predictable UUIDs.
- *
- * @example
- * ```typescript
- * import { setupCryptoMocks, createMockUuid } from '@levelcode/common/testing/mocks/crypto'
- *
- * // Setup deterministic UUIDs
- * const spies = setupCryptoMocks()
- * await runTest()
- * spies.restore()
- *
- * // Or create specific UUIDs
- * const uuid = createMockUuid('test-prefix')
- * // Returns: 'test-prefix-0000-0000-0000-000000000000'
- * ```
- */
-import { spyOn } from 'bun:test';
-/**
- * A valid UUID v4 format string.
- */
-export type UUID = `${string}-${string}-${string}-${string}-${string}`;
-/**
- * Options for setting up crypto mocks.
- */
-export interface SetupCryptoMocksOptions {
-    /**
-     * A prefix to use for generated UUIDs.
-     * The format will be: `{prefix}-0000-0000-0000-000000000000`
-     * @default 'mock-uuid'
-     */
-    prefix?: string;
-    /**
-     * Whether to generate sequential UUIDs.
-     * If true, each call returns a different UUID: mock-uuid-1, mock-uuid-2, etc.
-     * @default false
-     */
-    sequential?: boolean;
-    /**
-     * A specific list of UUIDs to return in order.
-     * If provided, UUIDs are returned from this list in sequence.
-     * When exhausted, falls back to default behavior.
-     */
-    uuids?: UUID[];
-}
-/**
- * Result of setting up crypto mocks.
- */
-export interface CryptoMockSpies {
-    /** The spy on randomUUID */
-    randomUUID: ReturnType<typeof spyOn>;
-    /** Restore the original implementation */
-    restore: () => void;
-    /** Clear call history */
-    clear: () => void;
-    /** Get the current call count */
-    getCallCount: () => number;
-}
-/**
- * Creates a deterministic mock UUID with a given prefix.
- *
- * @param prefix - The prefix for the UUID
- * @param index - Optional index for sequential UUIDs
- * @returns A valid UUID-format string
- *
- * @example
- * ```typescript
- * createMockUuid('test')
- * // Returns: 'test-uuid-0000-0000-000000000000'
- *
- * createMockUuid('test', 5)
- * // Returns: 'test-uuid-0000-0005-000000000000'
- * ```
- */
-export declare function createMockUuid(prefix: string, index?: number): UUID;
-/**
- * Sets up a spy on crypto.randomUUID with deterministic behavior.
- *
- * @param options - Configuration options
- * @returns Object containing the spy and cleanup utilities
- *
- * @example
- * ```typescript
- * describe('my test', () => {
- *   let cryptoSpies: CryptoMockSpies
- *
- *   beforeEach(() => {
- *     cryptoSpies = setupCryptoMocks({ prefix: 'test' })
- *   })
- *
- *   afterEach(() => {
- *     cryptoSpies.restore()
- *   })
- *
- *   it('creates deterministic IDs', async () => {
- *     const result = await createSomething()
- *     expect(result.id).toBe('test-0000-0000-0000-000000000000')
- *   })
- * })
- * ```
- */
-export declare function setupCryptoMocks(options?: SetupCryptoMocksOptions): CryptoMockSpies;
-/**
- * Sets up crypto mocks that return specific UUIDs in sequence.
- * Useful when you need specific IDs for assertions.
- *
- * @param uuids - The UUIDs to return in order
- * @returns Object containing the spy and cleanup utilities
- *
- * @example
- * ```typescript
- * const spies = setupSequentialCryptoMocks([
- *   'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
- *   'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
- * ])
- *
- * crypto.randomUUID() // 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
- * crypto.randomUUID() // 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'
- * crypto.randomUUID() // 'mock-uuid-0000-0000-0000-000000000002' (fallback)
- * ```
- */
-export declare function setupSequentialCryptoMocks(uuids: UUID[]): CryptoMockSpies;
-/**
- * A set of commonly used test UUIDs for consistency across tests.
- */
-export declare const TEST_UUIDS: {
-    /** Default user ID for tests */
-    readonly USER: UUID;
-    /** Default session ID for tests */
-    readonly SESSION: UUID;
-    /** Default run ID for tests */
-    readonly RUN: UUID;
-    /** Default step ID for tests */
-    readonly STEP: UUID;
-    /** Default message ID for tests */
-    readonly MESSAGE: UUID;
-    /** Default agent ID for tests */
-    readonly AGENT: UUID;
-};
-/**
- * Creates a UUID generator that returns sequential UUIDs with a prefix.
- * Useful for generating multiple related IDs.
- *
- * @param prefix - The prefix for generated UUIDs
- * @returns A function that generates sequential UUIDs
- *
- * @example
- * ```typescript
- * const generateId = createUuidGenerator('item')
- *
- * generateId() // 'item-uuid-0000-0000-000000000000'
- * generateId() // 'item-uuid-0000-0001-000000000000'
- * generateId() // 'item-uuid-0000-0002-000000000000'
- * ```
- */
-export declare function createUuidGenerator(prefix: string): () => UUID;