// @ts-nocheck
/**
 * Type declarations for the `@framers/agentos-skills` content package.
 *
 * Describes the shape of `registry.json` — the machine-readable index of all
 * bundled SKILL.md prompt modules. These types are consumed by
 * `@framers/agentos-skills-registry` (the catalog SDK) and any tooling that
 * reads the registry directly.
 *
 * @module @framers/agentos-skills
 */

/** Supported package-manager / install strategies for skill prerequisites. */
export type SkillInstallKind = 'brew' | 'apt' | 'node' | 'go' | 'uv' | 'download';

/**
 * Describes how to install a single prerequisite binary for a skill.
 *
 * Each install spec maps to a concrete command the agent or user can run
 * (e.g. `brew install gh`, `npm install -g typescript`).
 */
export interface SkillInstallSpec {
  /** Unique ID for this install option (e.g. 'brew-gh') */
  id?: string;
  /** Package manager or install strategy */
  kind: SkillInstallKind;
  /** Human-readable label for the install option */
  label?: string;
  /** Binary names this install provides (used for verification) */
  bins?: string[];
  /** OS restrictions — only show this option on matching platforms */
  os?: readonly string[];
  /** Homebrew formula name */
  formula?: string;
  /** npm / pip / go package name */
  package?: string;
  /** Node module name (for `npx`-style invocation) */
  module?: string;
  /** Direct download URL */
  url?: string;
  /** Archive filename within the download */
  archive?: string;
  /** Whether to extract the download */
  extract?: boolean;
  /** Number of directory levels to strip when extracting */
  stripComponents?: number;
  /** Target directory for the extracted/downloaded binary */
  targetDir?: string;
}

/**
 * Binary, environment variable, and config requirements that must be met
 * before a skill is eligible to run.
 */
export interface SkillRequirements {
  /** All of these binaries must be on PATH */
  bins?: string[];
  /** At least one of these binaries must be on PATH */
  anyBins?: string[];
  /** All of these environment variables must be set */
  env?: string[];
  /** All of these config file paths must exist */
  config?: string[];
}

/**
 * Structured metadata extracted from the `metadata.agentos` block in SKILL.md
 * frontmatter. Controls eligibility, discoverability, and installation UX.
 */
export interface SkillMetadata {
  /** If true, skill is always included in agent context (no opt-in needed) */
  always?: boolean;
  /** Override key used for per-skill config in agent.config.json */
  skillKey?: string;
  /** Primary environment variable this skill needs (e.g. 'GITHUB_TOKEN') */
  primaryEnv?: string;
  /** Emoji icon for display in catalogs and CLI */
  emoji?: string;
  /** URL to the skill's homepage or docs */
  homepage?: string;
  /** OS restrictions — skill only available on these platforms */
  os?: readonly string[];
  /** Binary and env requirements for eligibility checking */
  requires?: SkillRequirements;
  /** Installation options for missing prerequisites */
  install?: SkillInstallSpec[];
}

/**
 * Shape of a single skill entry in `registry.json`.
 *
 * Each entry maps to one `registry/curated/{name}/SKILL.md` file and includes
 * all metadata needed for catalog queries without reading the file from disk.
 */
export interface SkillRegistryEntry {
  /** Fully-qualified ID (e.g. 'com.framers.skill.github') */
  id: string;
  /** Unique slug matching the directory name under registry/curated/ */
  name: string;
  /** Human-readable display name (e.g. 'GitHub') */
  displayName?: string;
  /** Semantic version from the SKILL.md frontmatter */
  version: string;
  /** Relative path from package root to the skill directory */
  path: string;
  /** Brief description of the skill's capabilities */
  description: string;
  /** Grouping category (e.g. 'developer', 'social', 'voice') */
  category?: string;
  /** Namespace used for registry scoping */
  namespace?: string;
  /** Whether this skill has been staff-verified */
  verified: boolean;
  /** Provenance: curated (staff-maintained) or community-submitted */
  source?: 'curated' | 'community';
  /** ISO timestamp of last verification */
  verifiedAt?: string;
  /** Searchable keywords */
  keywords?: string[];
  /** Secret identifiers the skill requires (e.g. 'github.token') */
  requiredSecrets?: string[];
  /** Tool identifiers the skill depends on */
  requiredTools?: string[];
  /** Structured metadata from the SKILL.md frontmatter */
  metadata?: SkillMetadata;
}

/** Aggregate counts for the registry. */
export interface SkillsRegistryStats {
  totalSkills: number;
  curatedCount: number;
  communityCount: number;
}

/**
 * Shape of the full `registry.json` file.
 *
 * Auto-generated by `scripts/update-registry.mjs` from the SKILL.md files
 * in `registry/curated/` and `registry/community/`.
 */
export interface SkillsRegistry {
  /** Schema version */
  version: string;
  /** ISO timestamp of last regeneration */
  updated: string;
  /** Category names present in each source */
  categories: {
    curated: string[];
    community: string[];
  };
  /** Skill entries grouped by source */
  skills: {
    curated: SkillRegistryEntry[];
    community: SkillRegistryEntry[];
  };
  /** Aggregate statistics */
  stats: SkillsRegistryStats;
}

declare const registry: SkillsRegistry;
export default registry;