/**
 * Skills system type definitions.
 *
 * Skills are modular capability packages that extend Flynn's abilities.
 * Each skill lives in its own directory with a manifest.json and SKILL.md.
 */

/** Three tiers of skills: shipped with Flynn, installed via CLI, or user-created. */
export type SkillTier = 'bundled' | 'managed' | 'workspace';

/** Requirements that must be met for a skill to be available. */
export interface SkillRequirements {
  /** OS platforms the skill supports (e.g., ['linux', 'darwin']). Empty = all. */
  os?: string[];
  /** Binaries that must exist in PATH (e.g., ['git', 'docker']). */
  binaries?: string[];
  /** Environment variables that must be set (e.g., ['GITHUB_TOKEN']). */
  env?: string[];
}

/** Installer spec for Homebrew packages. */
export interface BrewInstallerSpec {
  type: 'brew';
  packages: string[];
}

/** Installer spec for Node.js packages. */
export interface NodeInstallerSpec {
  type: 'node';
  packages: string[];
}

/** Installer spec for Go packages. */
export interface GoInstallerSpec {
  type: 'go';
  packages: string[];
}

/** Installer spec for direct downloads. */
export interface DownloadInstallerSpec {
  type: 'download';
  url: string;
  destination?: string;
}

/** Supported installer variants declared in skill manifests. */
export type SkillInstallerSpec =
  | BrewInstallerSpec
  | NodeInstallerSpec
  | GoInstallerSpec
  | DownloadInstallerSpec;

export interface SkillFsPermissions {
  /** Allowed path globs for read-only filesystem access. */
  read?: string[];
  /** Allowed path globs for write filesystem access (includes edits/patches). */
  write?: string[];
}

export interface SkillNetPermission {
  /** Host glob, e.g. "api.todoist.com" or "*.example.com". */
  host: string;
  /** Allowed ports. If omitted, any port is allowed. */
  ports?: number[];
}

export interface SkillPermissions {
  /** Allowed tool groups, e.g. ["group:fs", "group:web"]. */
  tool_groups?: string[];
  /** Allowed tool name patterns (glob). Overrides tool_groups when present. */
  tools?: string[];
  /** Filesystem access constraints (optional). */
  fs?: SkillFsPermissions;
  /** Network access constraints (optional). */
  net?: SkillNetPermission[];
  /** Named secret scopes required for credentialed actions (optional). */
  secrets?: string[];
  /**
   * Execution environment preference for high-risk operations.
   * - sandbox: run high-risk tools in the session sandbox (default)
   * - host: allow high-risk tools on the host (escape hatch)
   */
  execution_environment?: 'sandbox' | 'host';
}

/** Manifest for a skill (manifest.json). */
export interface SkillManifest {
  /** Unique skill name (e.g., 'git', 'web-search'). */
  name: string;
  /** Human-readable description. */
  description: string;
  /** Semantic version string. */
  version: string;
  /** Author name or identifier. */
  author?: string;
  /** Skill tier. */
  tier: SkillTier;
  /** System requirements for availability gating. */
  requirements?: SkillRequirements;
  /** Tool names this skill provides (informational — not enforced). */
  tools?: string[];
  /** npm/system dependencies needed. */
  dependencies?: string[];
  /** Optional dependency installers for future automated setup. */
  installers?: SkillInstallerSpec[];
  /** Optional capability declarations. Used for runtime policy enforcement. */
  permissions?: SkillPermissions;
}

/** A loaded skill ready for use. */
export interface Skill {
  /** The parsed manifest. */
  manifest: SkillManifest;
  /** Content of SKILL.md — injected into the system prompt. */
  instructions: string;
  /** Absolute path to the skill directory. */
  directory: string;
  /** Whether the skill's requirements are met on this system. */
  available: boolean;
  /** If not available, the reason(s) why. */
  unavailableReasons?: string[];
}
