@pikku/core 0.12.2 → 0.12.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -41,8 +41,10 @@
     "./services": "./dist/services/index.js",
     "./services/local-content": "./dist/services/local-content.js",
     "./services/gopass-secrets": "./dist/services/gopass-secrets.js",
+    "./crypto-utils": "./dist/crypto-utils.js",
     "./internal": "./dist/internal.js",
-    "./schema": "./dist/schema.js"
+    "./schema": "./dist/schema.js",
+    "./testing": "./dist/testing/index.js"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",

package/dist/wirings/ai-agent/ai-agent-assistant-ui.d.ts

@@ -1,5 +0,0 @@
-import type { AIStreamChannel, AIAgentInput } from './ai-agent.types.js';
-export declare function createAssistantUIChannel(parent: AIStreamChannel): AIStreamChannel;
-export declare function parseAssistantUIInput(input: Record<string, unknown>, defaults?: {
-    resourceId?: string;
-}): AIAgentInput;

package/dist/wirings/ai-agent/ai-agent-assistant-ui.js

@@ -1,168 +0,0 @@
-import { randomUUID } from 'crypto';
-export function createAssistantUIChannel(parent) {
-    const messageId = randomUUID();
-    let started = false;
-    let totalInputTokens = 0;
-    let totalOutputTokens = 0;
-    let pendingToolResults = [];
-    let hasToolCalls = false;
-    let hasPendingApproval = false;
-    const sendChunk = (chunk) => {
-        parent.send(chunk);
-    };
-    const ensureStarted = () => {
-        if (!started) {
-            started = true;
-            sendChunk({ type: 'start', messageId });
-        }
-    };
-    const flushToolResults = () => {
-        for (const chunk of pendingToolResults) {
-            sendChunk(chunk);
-        }
-        pendingToolResults = [];
-    };
-    return {
-        channelId: parent.channelId,
-        openingData: parent.openingData,
-        get state() {
-            return parent.state;
-        },
-        close: () => parent.close(),
-        sendBinary: (data) => parent.sendBinary(data),
-        send: (event) => {
-            switch (event.type) {
-                case 'text-delta':
-                    ensureStarted();
-                    sendChunk({ type: 'text-delta', textDelta: event.text });
-                    break;
-                case 'reasoning-delta':
-                    ensureStarted();
-                    sendChunk({ type: 'reasoning-delta', delta: event.text });
-                    break;
-                case 'audio-delta':
-                    ensureStarted();
-                    sendChunk({ type: 'audio-delta', data: event });
-                    break;
-                case 'audio-done':
-                    ensureStarted();
-                    sendChunk({ type: 'audio-done', data: event });
-                    break;
-                case 'tool-call':
-                    ensureStarted();
-                    hasToolCalls = true;
-                    sendChunk({
-                        type: 'tool-call-start',
-                        id: event.toolCallId,
-                        toolCallId: event.toolCallId,
-                        toolName: event.toolName,
-                    });
-                    sendChunk({
-                        type: 'tool-call-delta',
-                        argsText: typeof event.args === 'string'
-                            ? event.args
-                            : JSON.stringify(event.args),
-                    });
-                    sendChunk({ type: 'tool-call-end' });
-                    break;
-                case 'tool-result':
-                    ensureStarted();
-                    pendingToolResults.push({
-                        type: 'tool-result',
-                        toolCallId: event.toolCallId,
-                        result: event.result,
-                    });
-                    break;
-                case 'agent-call':
-                case 'agent-result':
-                    break;
-                case 'usage': {
-                    ensureStarted();
-                    totalInputTokens += event.tokens.input;
-                    totalOutputTokens += event.tokens.output;
-                    const hasPending = pendingToolResults.length > 0;
-                    sendChunk({
-                        type: 'finish-step',
-                        finishReason: hasToolCalls ? 'tool-calls' : 'stop',
-                        usage: {
-                            promptTokens: event.tokens.input,
-                            completionTokens: event.tokens.output,
-                        },
-                        isContinued: hasPending,
-                    });
-                    flushToolResults();
-                    hasToolCalls = false;
-                    break;
-                }
-                case 'error':
-                    ensureStarted();
-                    sendChunk({ type: 'error', errorText: event.message });
-                    break;
-                case 'approval-request':
-                    ensureStarted();
-                    hasPendingApproval = true;
-                    sendChunk({ type: 'data-approval-request', data: event });
-                    break;
-                case 'suspended':
-                    ensureStarted();
-                    sendChunk({ type: 'data-suspended', data: event });
-                    break;
-                case 'done':
-                    ensureStarted();
-                    flushToolResults();
-                    sendChunk({
-                        type: 'finish',
-                        finishReason: hasPendingApproval ? 'tool-calls' : 'stop',
-                        usage: {
-                            promptTokens: totalInputTokens,
-                            completionTokens: totalOutputTokens,
-                        },
-                    });
-                    parent.send('[DONE]');
-                    parent.close();
-                    break;
-            }
-        },
-    };
-}
-export function parseAssistantUIInput(input, defaults) {
-    const messages = input.messages;
-    if (!messages || !Array.isArray(messages) || messages.length === 0) {
-        throw new Error('assistant-ui input must contain a non-empty messages array');
-    }
-    const lastUserMessage = [...messages].reverse().find((m) => m.role === 'user');
-    if (!lastUserMessage) {
-        throw new Error('No user message found in assistant-ui input');
-    }
-    let messageText;
-    let attachments;
-    const extractFromParts = (parts) => {
-        const textParts = parts.filter((p) => p.type === 'text');
-        messageText = textParts.map((p) => String(p.text)).join(' ') || '';
-        const nonTextParts = parts.filter((p) => p.type === 'image' || p.type === 'file');
-        if (nonTextParts.length > 0) {
-            attachments = nonTextParts.map((p) => ({
-                type: p.type,
-                data: p.data,
-                url: p.url,
-                mediaType: p.mediaType,
-                filename: p.filename,
-            }));
-        }
-    };
-    if (typeof lastUserMessage.content === 'string') {
-        messageText = lastUserMessage.content;
-    }
-    else if (Array.isArray(lastUserMessage.parts)) {
-        extractFromParts(lastUserMessage.parts);
-    }
-    else if (Array.isArray(lastUserMessage.content)) {
-        extractFromParts(lastUserMessage.content);
-    }
-    else {
-        messageText = '';
-    }
-    const threadId = input.threadId ?? input.id ?? randomUUID();
-    const resourceId = defaults?.resourceId ?? 'default';
-    return { message: messageText, threadId, resourceId, attachments };
-}

package/src/crypto-utils.test.ts

@@ -1,116 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert'
-import { encryptJSON, decryptJSON } from './crypto-utils.js'
-
-describe('encryptJSON / decryptJSON', () => {
-  const secret = 'test-secret-key-for-encryption'
-
-  test('should round-trip a simple object', async () => {
-    const original = { hello: 'world', num: 42 }
-    const encrypted = await encryptJSON(secret, original)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.deepStrictEqual(decrypted, original)
-  })
-
-  test('should round-trip a string value', async () => {
-    const original = 'just a string'
-    const encrypted = await encryptJSON(secret, original)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.strictEqual(decrypted, original)
-  })
-
-  test('should round-trip a number', async () => {
-    const original = 12345
-    const encrypted = await encryptJSON(secret, original)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.strictEqual(decrypted, original)
-  })
-
-  test('should round-trip null', async () => {
-    const encrypted = await encryptJSON(secret, null)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.strictEqual(decrypted, null)
-  })
-
-  test('should round-trip a boolean', async () => {
-    const encrypted = await encryptJSON(secret, true)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.strictEqual(decrypted, true)
-  })
-
-  test('should round-trip a nested object', async () => {
-    const original = { user: { id: 1, roles: ['admin', 'user'] }, active: true }
-    const encrypted = await encryptJSON(secret, original)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.deepStrictEqual(decrypted, original)
-  })
-
-  test('should round-trip an array', async () => {
-    const original = [1, 'two', { three: 3 }]
-    const encrypted = await encryptJSON(secret, original)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.deepStrictEqual(decrypted, original)
-  })
-
-  test('should produce different ciphertexts for same input (random IV)', async () => {
-    const value = { same: 'data' }
-    const enc1 = await encryptJSON(secret, value)
-    const enc2 = await encryptJSON(secret, value)
-    assert.notStrictEqual(enc1, enc2)
-  })
-
-  test('should produce a base64url string (no +, /, or = characters)', async () => {
-    const encrypted = await encryptJSON(secret, { test: 'base64url' })
-    assert.ok(!/[+/=]/.test(encrypted), `Expected base64url, got: ${encrypted}`)
-  })
-
-  test('should fail to decrypt with wrong secret', async () => {
-    const encrypted = await encryptJSON(secret, { data: 'sensitive' })
-    await assert.rejects(
-      () => decryptJSON('wrong-secret', encrypted),
-      (err: any) => err instanceof Error
-    )
-  })
-
-  test('should reject an invalid encrypted payload (too short)', async () => {
-    await assert.rejects(() => decryptJSON(secret, 'dG9vc2hvcnQ'), {
-      message: 'Invalid encrypted payload',
-    })
-  })
-
-  test('should reject empty string', async () => {
-    await assert.rejects(() => decryptJSON(secret, ''), {
-      message: 'Invalid encrypted payload',
-    })
-  })
-
-  test('should reject corrupted ciphertext', async () => {
-    const encrypted = await encryptJSON(secret, { data: 'test' })
-    const corrupted = encrypted.slice(0, -4) + 'XXXX'
-    await assert.rejects(
-      () => decryptJSON(secret, corrupted),
-      (err: any) => err instanceof Error
-    )
-  })
-
-  test('should handle unicode content', async () => {
-    const original = { emoji: '🎉', japanese: 'こんにちは', arabic: 'مرحبا' }
-    const encrypted = await encryptJSON(secret, original)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.deepStrictEqual(decrypted, original)
-  })
-
-  test('should handle empty object', async () => {
-    const original = {}
-    const encrypted = await encryptJSON(secret, original)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.deepStrictEqual(decrypted, original)
-  })
-
-  test('should handle large payload', async () => {
-    const original = { data: 'x'.repeat(10000) }
-    const encrypted = await encryptJSON(secret, original)
-    const decrypted = await decryptJSON(secret, encrypted)
-    assert.deepStrictEqual(decrypted, original)
-  })
-})

package/src/crypto-utils.ts

@@ -1,99 +0,0 @@
-const encoder = new TextEncoder()
-const decoder = new TextDecoder()
-
-const getSubtle = () => {
-  const crypto = globalThis.crypto
-  if (!crypto?.subtle) {
-    throw new Error('WebCrypto not available')
-  }
-  return crypto.subtle
-}
-
-const base64Encode = (bytes: Uint8Array): string => {
-  if (typeof Buffer !== 'undefined') {
-    return Buffer.from(bytes).toString('base64')
-  }
-  let binary = ''
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]!)
-  }
-  return btoa(binary)
-}
-
-const base64Decode = (input: string): Uint8Array => {
-  if (typeof Buffer !== 'undefined') {
-    return new Uint8Array(Buffer.from(input, 'base64'))
-  }
-  const binary = atob(input)
-  const bytes = new Uint8Array(binary.length)
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i)
-  }
-  return bytes
-}
-
-const toBase64Url = (bytes: Uint8Array): string => {
-  return base64Encode(bytes)
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=+$/g, '')
-}
-
-const fromBase64Url = (input: string): Uint8Array => {
-  let base64 = input.replace(/-/g, '+').replace(/_/g, '/')
-  while (base64.length % 4 !== 0) base64 += '='
-  return base64Decode(base64)
-}
-
-const deriveKey = async (secret: string): Promise<CryptoKey> => {
-  const subtle = getSubtle()
-  const hash = await subtle.digest('SHA-256', encoder.encode(secret))
-  return subtle.importKey('raw', hash, { name: 'AES-GCM' }, false, [
-    'encrypt',
-    'decrypt',
-  ])
-}
-
-export const encryptJSON = async (
-  secret: string,
-  value: unknown
-): Promise<string> => {
-  const crypto = globalThis.crypto
-  if (!crypto?.getRandomValues) {
-    throw new Error('WebCrypto not available')
-  }
-  const subtle = getSubtle()
-  const iv = crypto.getRandomValues(new Uint8Array(12))
-  const key = await deriveKey(secret)
-  const plaintext = encoder.encode(JSON.stringify(value))
-  const encrypted = await subtle.encrypt(
-    { name: 'AES-GCM', iv },
-    key,
-    plaintext
-  )
-  const cipherBytes = new Uint8Array(encrypted)
-  const out = new Uint8Array(iv.length + cipherBytes.length)
-  out.set(iv, 0)
-  out.set(cipherBytes, iv.length)
-  return toBase64Url(out)
-}
-
-export const decryptJSON = async <T>(
-  secret: string,
-  token: string
-): Promise<T> => {
-  const subtle = getSubtle()
-  const data = fromBase64Url(token)
-  if (data.length < 13) {
-    throw new Error('Invalid encrypted payload')
-  }
-  const iv = data.slice(0, 12)
-  const ciphertext = data.slice(12)
-  const key = await deriveKey(secret)
-  const decrypted = await subtle.decrypt(
-    { name: 'AES-GCM', iv },
-    key,
-    ciphertext
-  )
-  return JSON.parse(decoder.decode(new Uint8Array(decrypted))) as T
-}

package/src/errors/error-handler.ts

@@ -1,62 +0,0 @@
-import { pikkuState } from '../pikku-state.js'
-
-/**
- * Base class for custom errors.
- * @extends {Error}
- */
-export class PikkuError extends Error {
-  /**
-   * Creates an instance of PikkuError.
-   * @param message - The error message.
-   */
-  constructor(message: string = 'An error occurred') {
-    super(message)
-    Object.setPrototypeOf(this, new.target.prototype)
-  }
-}
-
-/**
- * Interface for error details.
- */
-export interface ErrorDetails {
-  status: number
-  message: string
-  mcpCode?: number
-}
-
-/**
- * Adds an error to the API errors map.
- * @param error - The error to add.
- * @param details - The details of the error.
- */
-export const addError = (error: any, { status, message }: ErrorDetails) => {
-  pikkuState(null, 'misc', 'errors').set(error, { status, message })
-}
-
-/**
- * Adds multiple errors to the API errors map.
- * @param errors - An array of errors and their details.
- */
-export const addErrors = (
-  errors: Array<[error: any, details: ErrorDetails]>
-) => {
-  errors.forEach((error) => {
-    addError(error[0], error[1])
-  })
-}
-
-/**
- * Retrieves the error response for a given error.
- * @param error - The error to get the response for.
- * @returns An object containing the status and message, or undefined if the error is not found.
- */
-export const getErrorResponse = (
-  error: Error
-): { status: number; message: string; mcpCode?: number } | undefined => {
-  const errors = Array.from(pikkuState(null, 'misc', 'errors').entries())
-  const foundError = errors.find(([e]) => e.name === error.constructor.name)
-  if (foundError) {
-    return foundError[1]
-  }
-  return pikkuState(null, 'misc', 'errors').get(error)
-}

package/src/errors/error.test.ts

@@ -1,195 +0,0 @@
-import { test, describe } from 'node:test'
-import assert from 'assert'
-import {
-  getErrorResponse,
-  addError,
-  addErrors,
-  PikkuError,
-} from './error-handler.js'
-import {
-  BadRequestError,
-  UnauthorizedError,
-  MissingSessionError,
-  InvalidSessionError,
-  PaymentRequiredError,
-  ForbiddenError,
-  InvalidOriginError,
-  NotFoundError,
-  MethodNotAllowedError,
-  NotAcceptableError,
-  ProxyAuthenticationRequiredError,
-  RequestTimeoutError,
-  ConflictError,
-  GoneError,
-  LengthRequiredError,
-  PreconditionFailedError,
-  PayloadTooLargeError,
-  URITooLongError,
-  UnsupportedMediaTypeError,
-  RangeNotSatisfiableError,
-  ExpectationFailedError,
-  UnprocessableContentError,
-  LockedError,
-  TooManyRequestsError,
-  InternalServerError,
-  NotImplementedError,
-  BadGatewayError,
-  ServiceUnavailableError,
-  GatewayTimeoutError,
-  HTTPVersionNotSupportedError,
-  MaxComputeTimeReachedError,
-  MissingSchemaError,
-  InvalidMiddlewareWireError,
-  PikkuMissingMetaError,
-} from './errors.js'
-
-describe('PikkuError', () => {
-  test('should create error with default message', () => {
-    const error = new PikkuError()
-    assert.strictEqual(error.message, 'An error occurred')
-  })
-
-  test('should create error with custom message', () => {
-    const error = new PikkuError('custom message')
-    assert.strictEqual(error.message, 'custom message')
-  })
-
-  test('should be instance of Error', () => {
-    const error = new PikkuError()
-    assert.ok(error instanceof Error)
-  })
-
-  test('should be instance of PikkuError', () => {
-    const error = new PikkuError()
-    assert.ok(error instanceof PikkuError)
-  })
-
-  test('subclasses should be instanceof PikkuError', () => {
-    assert.ok(new BadRequestError() instanceof PikkuError)
-    assert.ok(new NotFoundError() instanceof PikkuError)
-    assert.ok(new ForbiddenError() instanceof PikkuError)
-  })
-})
-
-describe('getErrorResponse', () => {
-  test('should return the correct error response for BadRequestError', () => {
-    const error = new BadRequestError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 400,
-      message:
-        'The server cannot or will not process the request due to client error (e.g., malformed request syntax).',
-    })
-  })
-
-  test('should return the correct error response for NotFoundError', () => {
-    const error = new NotFoundError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 404,
-      message: 'The server cannot find the requested resource.',
-    })
-  })
-
-  test('should return the correct error response for ForbiddenError', () => {
-    const error = new ForbiddenError()
-    const response = getErrorResponse(error)
-    assert.deepStrictEqual(response, {
-      status: 403,
-      message:
-        'The client does not have permission to access the requested resource.',
-    })
-  })
-
-  test('should return undefined for an unknown error', () => {
-    class UnknownError extends Error {}
-    const error = new UnknownError()
-    const response = getErrorResponse(error)
-    assert.strictEqual(response, undefined)
-  })
-
-  test('should return the correct error response for a custom error added to apiErrors', () => {
-    class CustomError extends Error {}
-    const customError = new CustomError()
-    const customErrorDetails = { status: 400, message: 'Custom Error' }
-
-    // Add the custom error to the apiErrors map
-    addError(CustomError, customErrorDetails)
-
-    const response = getErrorResponse(customError)
-    assert.deepStrictEqual(response, customErrorDetails)
-  })
-})
-
-describe('addErrors', () => {
-  test('should register multiple errors at once', () => {
-    class ErrA extends Error {}
-    class ErrB extends Error {}
-    addErrors([
-      [ErrA, { status: 450, message: 'Error A' }],
-      [ErrB, { status: 451, message: 'Error B' }],
-    ])
-    assert.deepStrictEqual(getErrorResponse(new ErrA()), {
-      status: 450,
-      message: 'Error A',
-    })
-    assert.deepStrictEqual(getErrorResponse(new ErrB()), {
-      status: 451,
-      message: 'Error B',
-    })
-  })
-})
-
-describe('all built-in error classes', () => {
-  const errorCases: [string, any, number][] = [
-    ['InvalidMiddlewareWireError', InvalidMiddlewareWireError, 500],
-    ['PikkuMissingMetaError', PikkuMissingMetaError, 500],
-    ['BadRequestError', BadRequestError, 400],
-    ['UnauthorizedError', UnauthorizedError, 401],
-    ['MissingSessionError', MissingSessionError, 401],
-    ['InvalidSessionError', InvalidSessionError, 401],
-    ['PaymentRequiredError', PaymentRequiredError, 402],
-    ['ForbiddenError', ForbiddenError, 403],
-    ['InvalidOriginError', InvalidOriginError, 403],
-    ['NotFoundError', NotFoundError, 404],
-    ['MethodNotAllowedError', MethodNotAllowedError, 405],
-    ['NotAcceptableError', NotAcceptableError, 406],
-    ['ProxyAuthenticationRequiredError', ProxyAuthenticationRequiredError, 407],
-    ['RequestTimeoutError', RequestTimeoutError, 408],
-    ['ConflictError', ConflictError, 409],
-    ['GoneError', GoneError, 410],
-    ['LengthRequiredError', LengthRequiredError, 411],
-    ['PreconditionFailedError', PreconditionFailedError, 412],
-    ['PayloadTooLargeError', PayloadTooLargeError, 413],
-    ['URITooLongError', URITooLongError, 414],
-    ['UnsupportedMediaTypeError', UnsupportedMediaTypeError, 415],
-    ['RangeNotSatisfiableError', RangeNotSatisfiableError, 416],
-    ['ExpectationFailedError', ExpectationFailedError, 417],
-    ['UnprocessableContentError', UnprocessableContentError, 422],
-    ['LockedError', LockedError, 423],
-    ['TooManyRequestsError', TooManyRequestsError, 429],
-    ['InternalServerError', InternalServerError, 500],
-    ['NotImplementedError', NotImplementedError, 501],
-    ['BadGatewayError', BadGatewayError, 502],
-    ['ServiceUnavailableError', ServiceUnavailableError, 503],
-    ['GatewayTimeoutError', GatewayTimeoutError, 504],
-    ['HTTPVersionNotSupportedError', HTTPVersionNotSupportedError, 505],
-    ['MaxComputeTimeReachedError', MaxComputeTimeReachedError, 524],
-    ['MissingSchemaError', MissingSchemaError, 500],
-  ]
-
-  for (const [name, ErrorClass, expectedStatus] of errorCases) {
-    test(`${name} should map to status ${expectedStatus}`, () => {
-      const error = new ErrorClass()
-      const response = getErrorResponse(error)
-      assert.ok(response, `Expected error response for ${name}`)
-      assert.strictEqual(response!.status, expectedStatus)
-      assert.ok(response!.message.length > 0)
-    })
-
-    test(`${name} should be instance of PikkuError`, () => {
-      const error = new ErrorClass()
-      assert.ok(error instanceof PikkuError)
-    })
-  }
-})