// file: libs/sdk/src/skill/index.ts

/**
 * Skills Module
 *
 * Skills are modular knowledge/workflow packages that teach AI how to perform
 * multi-step tasks using tools. Unlike tools (individual actions), skills are
 * recipes/playbooks that combine tools into coherent workflows.
 *
 * Aligned with the Anthropic Agent Skills specification, supporting:
 * - SKILL.md frontmatter parsing
 * - Skill directory loading (scripts/, references/, assets/)
 * - Spec fields: license, compatibility, specMetadata, allowedTools, resources
 * - Strict name validation (kebab-case, max 64 chars)
 *
 * @example Defining a skill with decorator
 * ```typescript
 * @Skill({
 *   name: 'review-pr',
 *   description: 'Review a GitHub pull request',
 *   instructions: `
 *     1. Fetch the PR details using github_get_pr
 *     2. Review each changed file...
 *   `,
 *   tools: ['github_get_pr', 'github_add_comment'],
 *   license: 'MIT',
 * })
 * class ReviewPRSkill extends SkillContext { ... }
 * ```
 *
 * @example Defining a skill with helper
 * ```typescript
 * const deploySkill = skill({
 *   name: 'deploy-app',
 *   description: 'Deploy application to production',
 *   instructions: { file: './skills/deploy.md' },
 *   tools: ['docker_build', 'k8s_apply'],
 * });
 * ```
 *
 * @example Loading a skill directory
 * ```typescript
 * const mySkill = await skillDir('./skills/review-pr');
 * ```
 *
 * @module skill
 */

// Registry
export { default as SkillRegistry } from './skill.registry';
export type { SkillRegistryInterface, IndexedSkill, SkillRegistryOptions, GetSkillsOptions } from './skill.registry';

// Instance
export { SkillInstance, createSkillInstance } from './skill.instance';

// Events
export { SkillEmitter } from './skill.events';
export type { SkillChangeEvent, SkillChangeKind, SkillChangeScope } from './skill.events';

// Storage
export type {
  SkillStorageProvider,
  SkillStorageProviderType,
  SkillSearchOptions,
  SkillSearchResult,
  SkillLoadResult,
  SkillListOptions,
  SkillListResult,
  MutableSkillStorageProvider,
} from './skill-storage.interface';

// Providers
export { MemorySkillProvider } from './providers/memory-skill.provider';
export type { MemorySkillProviderOptions } from './providers/memory-skill.provider';
export { ExternalSkillProviderBase } from './providers/external-skill.provider';
export type {
  ExternalSkillMode,
  ExternalSkillProviderOptions,
  ExternalSkillSearchOptions,
  ExternalSkillListOptions,
} from './providers/external-skill.provider';

// Validator
export { SkillToolValidator } from './skill-validator';
export type { ToolValidationResult } from './skill-validator';

// Factory
export { createSkillStorageProvider, createMemorySkillProvider } from './skill-storage.factory';
export type {
  SkillStorageFactoryOptions,
  SkillStorageFactoryResult,
  VectorDBSkillProviderOptions,
  ExternalSkillProviderConfig,
  ExtendedSkillStorageFactoryResult,
} from './skill-storage.factory';

// Sync
export {
  computeSkillHash,
  computeSkillHashComponents,
  areSkillsEqual,
  createEmptySyncState,
  serializeSyncState,
  deserializeSyncState,
  MemorySyncStateStore,
} from './sync';
export type {
  SkillHashComponents,
  SkillSyncStatus,
  SkillSyncEntry,
  SkillSyncState,
  SerializedSkillSyncState,
  SkillSyncStateStore,
  SyncResult,
} from './sync';

// Utilities
export {
  normalizeSkill,
  isSkillRecord,
  skillDiscoveryDeps,
  collectSkillMetadata,
  loadInstructions,
  buildSkillContent,
  formatSkillForLLM,
} from './skill.utils';

// SKILL.md Parser
export {
  parseSkillMdFrontmatter,
  skillMdFrontmatterToMetadata,
  loadSkillMdFile,
  stripFrontmatter,
} from './skill-md-parser';
export type { SkillMdParseResult } from './skill-md-parser';

// Directory Loader
export { loadSkillDirectory, scanSkillResources, skillDir } from './skill-directory-loader';
export type { ScanResult } from './skill-directory-loader';

// Semantic search extension point
export { SkillSemanticSearchToken } from './semantic/skill-semantic-search.interface';
export type { SkillSemanticSearchProvider } from './semantic/skill-semantic-search.interface';

// Sandboxed `scripts/` execution runtime is deferred to v1.7 ("Sandbox &
// CodeCall Expansion") so it can land alongside the production-grade
// isolation primitives (sandbox-exec / bubblewrap / seccomp) and a unified
// policy engine. v1.2 ships skill bundles that may carry a `scripts/`
// directory, but the SDK does not execute them — the host's existing tool
// surface or v1.3 sandboxed-process execution is the supported path.

// HTTP Utilities
export {
  formatSkillsForLlmCompact,
  formatSkillsForLlmFull,
  formatSkillForLLMWithSchemas,
  skillToApiResponse,
  filterSkillsByVisibility,
} from './skill-http.utils';
export type { CompactSkillSummary } from './skill-http.utils';

// Flows
export { SearchSkillsFlow, LoadSkillFlow } from './flows';

// Skill resources are served exclusively under the SEP-2640 `skill://`
// URI scheme. The legacy plural `skills://` scheme has been removed.
export {
  SEP_2640_EXTENSION_ID,
  SEP_2640_META_NAMESPACE,
  SKILL_ARCHIVE_MIME_TYPES,
  SKILL_INDEX_MIME_TYPE,
  SKILL_INDEX_SCHEMA_URI,
  SKILL_INDEX_URI,
  SKILL_MD_MIME_TYPE,
  SKILL_MD_PRIORITY,
  SKILL_SUPPORT_PRIORITY,
  SKILL_URI_SCHEME,
  buildArchiveIndexEntry,
  buildResourceTemplateIndexEntry,
  buildSkillIndex,
  buildSkillMdIndexEntry,
  buildSkillUri,
  isSkillIndexUri,
  isSkillUri,
  parseSkillUri,
  parseSkillUriWithKnownSkill,
  serializeSkillMd,
  validateSkillPath,
  type ParsedSkillUri,
  type SkillIndexDocument,
  type SkillIndexEntry,
  type SkillIndexEntryType,
} from './sep-2640';
export {
  getSep2640Resources,
  Sep2640SkillFileResource,
  Sep2640SkillIndexResource,
  Sep2640SkillMdResource,
} from './sep-2640/resources';
export {
  findAndLoadSkillByPath,
  findSkillByPath,
  getSepVisibleSkills,
  readSkillFileByPath,
} from './sep-2640/sep-2640.resource-helpers';

// Authorities enforcement helpers (deny on load/read, filter on discovery)
export { assertSkillAuthorized, filterSkillsByAuthorities, getSkillAuthorities } from './skill-authorities.helper';
export { findNestedSkillMd } from './skill-directory-loader';

// Session Management
export { SkillSessionManager } from './session/skill-session.manager';
export { MemorySkillSessionStore, createSkillSessionStore } from './session/skill-session-store.interface';
export type { SkillSessionStore } from './session/skill-session-store.interface';
export { serializeSessionState, deserializeSessionState, createEmptySessionState } from './session/skill-session.types';
export type {
  SkillSessionState,
  SkillSessionOptions,
  SkillActivationResult,
  ToolAuthorizationResult,
  SkillSessionEvent,
  SkillSecurityPolicy,
  SkillPolicyMode,
  SerializedSkillSessionState,
} from './session/skill-session.types';

// Guards
export { ToolAuthorizationGuard } from './guards/tool-authorization.guard';
export type { ToolAuthorizationGuardOptions } from './guards/tool-authorization.guard';

// Hooks
export { createSkillToolGuardHook, type SkillToolGuardHookOptions, type SkillToolGuardHookClass } from './hooks';

// Errors
export { ToolNotAllowedError, ToolApprovalRequiredError } from './errors/tool-not-allowed.error';
export { SkillValidationError } from './errors/skill-validation.error';
export type { SkillValidationResult, SkillValidationReport } from './errors/skill-validation.error';

// Scope Helper
export { registerSkillCapabilities } from './skill-scope.helper';
export type { SkillScopeRegistrationOptions } from './skill-scope.helper';

// Skill Audit Helper
export { registerSkillAuditWriter, setSkillAuditFactory, hasSkillAuditFactory } from './skill-audit.helper';
export type { AuditModuleShape, SkillAuditFactory } from './skill-audit.helper';

// Mode Utilities
export { detectSkillsOnlyMode, isSkillsOnlySession } from './skill-mode.utils';
export type { SkillsOnlySessionPayload } from './skill-mode.utils';

// Initialize-instructions composition (used by stdio + HTTP transports;
// re-exported so embedders can build their own initialize response strings).
export {
  buildSkillsCatalogSummary,
  composeInitializeInstructions,
  buildChannelInstructions,
} from './skill-instructions.helper';
export type { InjectInstructionsPolicy } from './skill-instructions.helper';

// HTTP Authentication
export { SkillHttpAuthValidator, createSkillHttpAuthValidator } from './auth';
export type { SkillHttpAuthContext, SkillHttpAuthResult, SkillHttpAuthValidatorOptions } from './auth';

// HTTP Caching
export {
  MemorySkillHttpCache,
  RedisSkillHttpCache,
  createSkillHttpCache,
  getSkillHttpCache,
  invalidateScopeCache,
  invalidateSkillInCache,
  disposeAllCaches,
} from './cache';
export type { SkillHttpCache, SkillHttpCacheOptions, SkillHttpCacheResult } from './cache';
