@llmist/testing 16.1.0 → 16.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Readable, PassThrough, Writable } from 'node:stream';
-import { LLMMessage, AbstractGadget, AudioMimeType, LLMGenerationOptions, ImageMimeType, ProviderAdapter, ModelDescriptor, LLMStream, ImageGenerationOptions, ImageGenerationResult, SpeechGenerationOptions, SpeechGenerationResult, LLMist, IConversationManager, LLMStreamChunk } from 'llmist';
+import { LLMMessage, AbstractGadget, AudioMimeType, LLMGenerationOptions, ImageMimeType, ProviderAdapter, ModelDescriptor, LLMStream, ImageGenerationOptions, ImageGenerationResult, SpeechGenerationOptions, SpeechGenerationResult, LLMist, IConversationManager, Skill, SkillActivation, SkillMetadata, SkillActivationOptions, ParsedSkill, LLMStreamChunk } from 'llmist';
 import { ZodType } from 'zod';
 
 /**
@@ -1353,6 +1353,105 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
+/**
+ * Testing utilities for skills.
+ *
+ * Provides helpers for parsing, activating, and asserting on skills
+ * without requiring filesystem setup.
+ *
+ * @module testing/skill-testing
+ */
+
+/**
+ * Parse and validate a SKILL.md content string.
+ *
+ * @param content - Full SKILL.md content (frontmatter + body)
+ * @param sourcePath - Optional source path (defaults to /test/SKILL.md)
+ * @returns Parsed skill with instructions loaded
+ *
+ * @example
+ * ```typescript
+ * import { testSkillParse } from '@llmist/testing';
+ *
+ * const parsed = testSkillParse(`---
+ * name: my-skill
+ * description: A test skill
+ * ---
+ * Do the thing.`);
+ *
+ * expect(parsed.metadata.name).toBe('my-skill');
+ * ```
+ */
+declare function testSkillParse(content: string, sourcePath?: string): ParsedSkill;
+/**
+ * Test a skill's activation with given arguments.
+ *
+ * @param skill - Skill instance to activate
+ * @param options - Activation options (arguments, cwd, etc.)
+ * @returns Activation result with resolved instructions
+ *
+ * @example
+ * ```typescript
+ * import { testSkillActivation, mockSkill } from '@llmist/testing';
+ *
+ * const skill = mockSkill({ name: 'search' });
+ * const activation = await testSkillActivation(skill, { arguments: '*.ts' });
+ * expect(activation.resolvedInstructions).toContain('*.ts');
+ * ```
+ */
+declare function testSkillActivation(skill: Skill, options?: SkillActivationOptions): Promise<SkillActivation>;
+/**
+ * Assert that a skill's resolved instructions contain expected content.
+ *
+ * @param activation - The activation result to check
+ * @param expected - Array of strings that must be present in the instructions
+ * @throws AssertionError if any expected string is missing
+ */
+declare function assertSkillContains(activation: SkillActivation, expected: string[]): void;
+/**
+ * Validate a SKILL.md content string and return any issues.
+ *
+ * @param content - Full SKILL.md content
+ * @returns Array of validation issues (empty if valid)
+ */
+declare function validateSkill(content: string): string[];
+/**
+ * Create a mock Skill instance for testing.
+ *
+ * @param overrides - Override any metadata fields
+ * @param instructions - Custom instructions body
+ */
+declare function mockSkill(overrides?: Partial<SkillMetadata>, instructions?: string): Skill;
+/**
+ * Fluent builder for creating test skills.
+ *
+ * @example
+ * ```typescript
+ * import { MockSkillBuilder } from '@llmist/testing';
+ *
+ * const skill = new MockSkillBuilder()
+ *   .withName('gmail-read')
+ *   .withDescription('Read Gmail messages')
+ *   .withInstructions('Use gws to read emails.')
+ *   .build();
+ * ```
+ */
+declare class MockSkillBuilder {
+    private _name;
+    private _description;
+    private _instructions;
+    private _overrides;
+    withName(name: string): this;
+    withDescription(description: string): this;
+    withInstructions(instructions: string): this;
+    withModel(model: string): this;
+    withContext(context: "fork" | "inline"): this;
+    withPaths(paths: string[]): this;
+    withAllowedTools(tools: string[]): this;
+    withGadgets(gadgets: string[]): this;
+    build(): Skill;
+}
+
 /**
  * Stream testing utilities for llmist.
  * Provides helpers for creating and consuming test streams.
@@ -1492,4 +1591,4 @@ interface MockTUIApp {
  */
 declare const createMockTUIApp: () => MockTUIApp;
 
-export { type MockAudioData, MockBuilder, MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type MockImageData, MockManager, type MockMatcher, type MockMatcherContext, type MockOptions, MockPromptRecorder, MockProviderAdapter, type MockRegistration, type MockResponse, type MockStats, type MockTUIApp, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockAdapter, createMockClient, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockStream, createMockTUIApp, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextMockStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getMockManager, getStreamFinalChunk, mockGadget, mockLLM, resetMocks, testGadget, testGadgetBatch, waitFor };
+export { type MockAudioData, MockBuilder, MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type MockImageData, MockManager, type MockMatcher, type MockMatcherContext, type MockOptions, MockPromptRecorder, MockProviderAdapter, type MockRegistration, type MockResponse, MockSkillBuilder, type MockStats, type MockTUIApp, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, assertSkillContains, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockAdapter, createMockClient, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockStream, createMockTUIApp, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextMockStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getMockManager, getStreamFinalChunk, mockGadget, mockLLM, mockSkill, resetMocks, testGadget, testGadgetBatch, testSkillActivation, testSkillParse, validateSkill, waitFor };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Readable, PassThrough, Writable } from 'node:stream';
-import { LLMMessage, AbstractGadget, AudioMimeType, LLMGenerationOptions, ImageMimeType, ProviderAdapter, ModelDescriptor, LLMStream, ImageGenerationOptions, ImageGenerationResult, SpeechGenerationOptions, SpeechGenerationResult, LLMist, IConversationManager, LLMStreamChunk } from 'llmist';
+import { LLMMessage, AbstractGadget, AudioMimeType, LLMGenerationOptions, ImageMimeType, ProviderAdapter, ModelDescriptor, LLMStream, ImageGenerationOptions, ImageGenerationResult, SpeechGenerationOptions, SpeechGenerationResult, LLMist, IConversationManager, Skill, SkillActivation, SkillMetadata, SkillActivationOptions, ParsedSkill, LLMStreamChunk } from 'llmist';
 import { ZodType } from 'zod';
 
 /**
@@ -1353,6 +1353,105 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
+/**
+ * Testing utilities for skills.
+ *
+ * Provides helpers for parsing, activating, and asserting on skills
+ * without requiring filesystem setup.
+ *
+ * @module testing/skill-testing
+ */
+
+/**
+ * Parse and validate a SKILL.md content string.
+ *
+ * @param content - Full SKILL.md content (frontmatter + body)
+ * @param sourcePath - Optional source path (defaults to /test/SKILL.md)
+ * @returns Parsed skill with instructions loaded
+ *
+ * @example
+ * ```typescript
+ * import { testSkillParse } from '@llmist/testing';
+ *
+ * const parsed = testSkillParse(`---
+ * name: my-skill
+ * description: A test skill
+ * ---
+ * Do the thing.`);
+ *
+ * expect(parsed.metadata.name).toBe('my-skill');
+ * ```
+ */
+declare function testSkillParse(content: string, sourcePath?: string): ParsedSkill;
+/**
+ * Test a skill's activation with given arguments.
+ *
+ * @param skill - Skill instance to activate
+ * @param options - Activation options (arguments, cwd, etc.)
+ * @returns Activation result with resolved instructions
+ *
+ * @example
+ * ```typescript
+ * import { testSkillActivation, mockSkill } from '@llmist/testing';
+ *
+ * const skill = mockSkill({ name: 'search' });
+ * const activation = await testSkillActivation(skill, { arguments: '*.ts' });
+ * expect(activation.resolvedInstructions).toContain('*.ts');
+ * ```
+ */
+declare function testSkillActivation(skill: Skill, options?: SkillActivationOptions): Promise<SkillActivation>;
+/**
+ * Assert that a skill's resolved instructions contain expected content.
+ *
+ * @param activation - The activation result to check
+ * @param expected - Array of strings that must be present in the instructions
+ * @throws AssertionError if any expected string is missing
+ */
+declare function assertSkillContains(activation: SkillActivation, expected: string[]): void;
+/**
+ * Validate a SKILL.md content string and return any issues.
+ *
+ * @param content - Full SKILL.md content
+ * @returns Array of validation issues (empty if valid)
+ */
+declare function validateSkill(content: string): string[];
+/**
+ * Create a mock Skill instance for testing.
+ *
+ * @param overrides - Override any metadata fields
+ * @param instructions - Custom instructions body
+ */
+declare function mockSkill(overrides?: Partial<SkillMetadata>, instructions?: string): Skill;
+/**
+ * Fluent builder for creating test skills.
+ *
+ * @example
+ * ```typescript
+ * import { MockSkillBuilder } from '@llmist/testing';
+ *
+ * const skill = new MockSkillBuilder()
+ *   .withName('gmail-read')
+ *   .withDescription('Read Gmail messages')
+ *   .withInstructions('Use gws to read emails.')
+ *   .build();
+ * ```
+ */
+declare class MockSkillBuilder {
+    private _name;
+    private _description;
+    private _instructions;
+    private _overrides;
+    withName(name: string): this;
+    withDescription(description: string): this;
+    withInstructions(instructions: string): this;
+    withModel(model: string): this;
+    withContext(context: "fork" | "inline"): this;
+    withPaths(paths: string[]): this;
+    withAllowedTools(tools: string[]): this;
+    withGadgets(gadgets: string[]): this;
+    build(): Skill;
+}
+
 /**
  * Stream testing utilities for llmist.
  * Provides helpers for creating and consuming test streams.
@@ -1492,4 +1591,4 @@ interface MockTUIApp {
  */
 declare const createMockTUIApp: () => MockTUIApp;
 
-export { type MockAudioData, MockBuilder, MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type MockImageData, MockManager, type MockMatcher, type MockMatcherContext, type MockOptions, MockPromptRecorder, MockProviderAdapter, type MockRegistration, type MockResponse, type MockStats, type MockTUIApp, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockAdapter, createMockClient, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockStream, createMockTUIApp, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextMockStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getMockManager, getStreamFinalChunk, mockGadget, mockLLM, resetMocks, testGadget, testGadgetBatch, waitFor };
+export { type MockAudioData, MockBuilder, MockConversationManager, type MockGadget, MockGadgetBuilder, type MockGadgetConfig, type MockImageData, MockManager, type MockMatcher, type MockMatcherContext, type MockOptions, MockPromptRecorder, MockProviderAdapter, type MockRegistration, type MockResponse, MockSkillBuilder, type MockStats, type MockTUIApp, type RecordedCall, type TestEnvironment, type TestEnvironmentOptions, type TestGadgetOptions, type TestGadgetResult, assertSkillContains, collectOutput, collectStream, collectStreamText, createAssistantMessage, createConversation, createConversationWithGadgets, createEmptyStream, createErrorStream, createLargeConversation, createMinimalConversation, createMockAdapter, createMockClient, createMockConversationManager, createMockGadget, createMockPrompt, createMockReadable, createMockStream, createMockTUIApp, createMockWritable, createSystemMessage, createTestEnvironment, createTestStream, createTextMockStream, createTextStream, createUserMessage, estimateTokens, getBufferedOutput, getMockManager, getStreamFinalChunk, mockGadget, mockLLM, mockSkill, resetMocks, testGadget, testGadgetBatch, testSkillActivation, testSkillParse, validateSkill, waitFor };

package/dist/index.js

@@ -2141,6 +2141,102 @@ function mockGadget() {
   return new MockGadgetBuilder();
 }
 
+// src/skill-testing.ts
+import {
+  parseSkillContent,
+  Skill,
+  validateMetadata
+} from "llmist";
+function testSkillParse(content, sourcePath = "/test/skill/SKILL.md") {
+  return parseSkillContent(content, sourcePath, { type: "directory", path: "/test/skill" }, true);
+}
+async function testSkillActivation(skill, options) {
+  return skill.activate({
+    ...options,
+    // Disable shell preprocessing in tests by default for safety
+    cwd: options?.cwd ?? "/test"
+  });
+}
+function assertSkillContains(activation, expected) {
+  for (const text of expected) {
+    if (!activation.resolvedInstructions.includes(text)) {
+      throw new Error(
+        `Expected skill instructions to contain "${text}" but it was not found.
+Instructions: ${activation.resolvedInstructions.slice(0, 500)}...`
+      );
+    }
+  }
+}
+function validateSkill(content) {
+  const parsed = testSkillParse(content);
+  return validateMetadata(parsed.metadata);
+}
+function mockSkill(overrides, instructions = "Mock skill instructions for testing.") {
+  const name = overrides?.name ?? "mock-skill";
+  const description = overrides?.description ?? "A mock skill for testing";
+  const metadataLines = Object.entries({ name, description, ...overrides }).filter(([_, v2]) => v2 !== void 0).map(([k2, v2]) => {
+    if (Array.isArray(v2)) return `${k2}:
+${v2.map((i) => `  - "${i}"`).join("\n")}`;
+    return `${k2}: ${v2}`;
+  }).join("\n");
+  return Skill.fromContent(
+    `---
+${metadataLines}
+---
+${instructions}`,
+    `/mock/${name}/SKILL.md`,
+    { type: "directory", path: `/mock/${name}` }
+  );
+}
+var MockSkillBuilder = class {
+  _name = "mock-skill";
+  _description = "A mock skill";
+  _instructions = "Mock instructions.";
+  _overrides = {};
+  withName(name) {
+    this._name = name;
+    return this;
+  }
+  withDescription(description) {
+    this._description = description;
+    return this;
+  }
+  withInstructions(instructions) {
+    this._instructions = instructions;
+    return this;
+  }
+  withModel(model) {
+    this._overrides.model = model;
+    return this;
+  }
+  withContext(context) {
+    this._overrides.context = context;
+    return this;
+  }
+  withPaths(paths) {
+    this._overrides.paths = paths;
+    return this;
+  }
+  withAllowedTools(tools) {
+    this._overrides["allowed-tools"] = tools;
+    return this;
+  }
+  withGadgets(gadgets) {
+    this._overrides.gadgets = gadgets;
+    return this;
+  }
+  build() {
+    return mockSkill(
+      {
+        name: this._name,
+        description: this._description,
+        ...this._overrides
+      },
+      this._instructions
+    );
+  }
+};
+
 // src/stream-helpers.ts
 function createTestStream(chunks) {
   return (async function* () {
@@ -18954,6 +19050,8 @@ export {
   MockManager,
   MockPromptRecorder,
   MockProviderAdapter,
+  MockSkillBuilder,
+  assertSkillContains,
   collectOutput,
   collectStream,
   collectStreamText,
@@ -18985,9 +19083,13 @@ export {
   getStreamFinalChunk,
   mockGadget,
   mockLLM,
+  mockSkill,
   resetMocks,
   testGadget,
   testGadgetBatch,
+  testSkillActivation,
+  testSkillParse,
+  validateSkill,
   waitFor
 };
 /*! Bundled license information: