export declare function addCommand(options: AddCommandOptions): Promise<{
    skillName: string;
    specifier: string;
} | {
    skillName: string;
    specifier: string;
}[] | {
    status: "listed";
    skills: SkillInfo[];
}>;

export declare type AddCommandOptions = {
    cwd: string;
    specifier: string;
    skill?: string | string[];
    global?: boolean;
    yes?: boolean;
    agent?: string[];
    list?: boolean;
    copy?: boolean;
    all?: boolean;
};

/**
 * Clone a git repo (shallow) into a temp dir, discover skills, then clean up.
 */
export declare function cloneAndDiscover(gitUrl: string, ref?: string): Promise<{
    skills: SkillInfo[];
    cleanup: () => Promise<void>;
}>;

/**
 * Converts a Node.js file system error to an appropriate SPM error type
 */
export declare function convertNodeError(error: NodeJS.ErrnoException, context: {
    operation: string;
    path: string;
}): FileSystemError;

export declare function createInstallProgressReporter(options?: ProgressReporterOptions): InstallProgressReporter;

/**
 * Discover skills in a local directory by scanning for SKILL.md files.
 * Recursively scans the repo tree for directories containing SKILL.md.
 */
export declare function discoverSkillsInDir(baseDir: string): Promise<SkillInfo[]>;

/**
 * Error codes for SPM (Skills Package Manager)
 * Inspired by pnpm's error code system
 */
export declare enum ErrorCode {
    FILE_NOT_FOUND = "ENOENT",
    PERMISSION_DENIED = "EACCES",
    FILE_EXISTS = "EEXIST",
    FS_ERROR = "EFS",
    GIT_CLONE_FAILED = "EGITCLONE",
    GIT_FETCH_FAILED = "EGITFETCH",
    GIT_CHECKOUT_FAILED = "EGITCHECKOUT",
    GIT_REF_NOT_FOUND = "EGITREF",
    GIT_NOT_INSTALLED = "EGITNOTFOUND",
    PARSE_ERROR = "EPARSE",
    JSON_PARSE_ERROR = "EJSONPARSE",
    YAML_PARSE_ERROR = "EYAMLPARSE",
    INVALID_SPECIFIER = "EINVALIDSPEC",
    MANIFEST_NOT_FOUND = "EMANIFEST",
    MANIFEST_EXISTS = "EMANIFESTEXISTS",
    MANIFEST_VALIDATION_ERROR = "EMANIFESTVAL",
    NETWORK_ERROR = "ENETWORK",
    REPO_NOT_FOUND = "EREPONOTFOUND",
    INSTALL_ERROR = "EINSTALL",
    UNKNOWN_ERROR = "EUNKNOWN",
    NOT_IMPLEMENTED = "ENOTIMPL",
    VALIDATION_ERROR = "EVALIDATION",
    SKILL_NOT_FOUND = "ESKILLNOTFOUND",
    SKILL_EXISTS = "ESKILLEXISTS"
}

export declare function expandSkillsManifest(_rootDir: string, manifest: SkillsManifest): Promise<NormalizedSkillsManifest>;

/**
 * Error thrown when file system operations fail
 */
export declare class FileSystemError extends SpmError {
    readonly operation: string;
    readonly path: string;
    constructor(options: {
        code: ErrorCode.FILE_NOT_FOUND | ErrorCode.PERMISSION_DENIED | ErrorCode.FILE_EXISTS | ErrorCode.FS_ERROR;
        operation: 'read' | 'write' | 'access' | 'mkdir' | 'rm' | 'copy' | 'symlink' | string;
        path: string;
        message?: string;
        cause?: Error;
    });
}

/**
 * Formats an error for display to the user
 * Provides helpful context for known error types
 */
export declare function formatErrorForDisplay(error: unknown): string;

/**
 * Gets the exit code for an error
 * Returns 1 for general errors, specific codes for known error types
 */
export declare function getExitCode(error: unknown): number;

/**
 * Error thrown when git operations fail
 */
export declare class GitError extends SpmError {
    readonly operation: string;
    readonly repoUrl?: string;
    readonly ref?: string;
    constructor(options: {
        code: ErrorCode.GIT_CLONE_FAILED | ErrorCode.GIT_FETCH_FAILED | ErrorCode.GIT_CHECKOUT_FAILED | ErrorCode.GIT_REF_NOT_FOUND | ErrorCode.GIT_NOT_INSTALLED;
        operation: 'clone' | 'fetch' | 'checkout' | 'ls-remote' | 'rev-parse' | string;
        repoUrl?: string;
        ref?: string;
        message?: string;
        cause?: Error;
    });
}

export declare function initCommand(options: InitCommandOptions, promptInit?: InitPrompter): Promise<SkillsManifest>;

export declare type InitCommandOptions = {
    cwd: string;
    yes?: boolean;
};

declare type InitPrompter = () => Promise<InitPromptResult>;

declare type InitPromptResult = {
    installDir: string;
    linkTargets: string[];
};

export declare function installCommand(options: InstallCommandOptions): Promise<{
    status: "skipped";
    reason: string;
    installed?: undefined;
} | {
    status: "installed";
    installed: string[];
    reason?: undefined;
}>;

export declare type InstallCommandOptions = {
    cwd: string;
    onProgress?: InstallProgressListener;
};

declare type InstallPhase = 'resolving' | 'fetching' | 'linking' | 'finalizing' | 'done';

export declare type InstallProgressEvent = {
    type: 'resolved';
    skillName: string;
} | {
    type: 'reused';
    skillName: string;
} | {
    type: 'downloaded';
    skillName: string;
} | {
    type: 'added';
    skillName: string;
} | {
    type: 'installed';
    skillName: string;
};

export declare type InstallProgressListener = (event: InstallProgressEvent) => void;

declare type InstallProgressReporter = {
    start(total: number): void;
    setPhase(phase: Exclude<InstallPhase, 'done'>): void;
    onProgress(event: InstallProgressEvent): void;
    complete(): void;
    fail(): void;
};

export declare function installSkills(rootDir: string, options?: {
    onProgress?: InstallProgressListener;
}): Promise<{
    status: "skipped";
    reason: string;
    installed?: undefined;
} | {
    status: "installed";
    installed: string[];
    reason?: undefined;
}>;

export declare const installStageHooks: {
    beforeFetch: (_rootDir: string, _manifest: SkillsManifest, _plan: ResolvedSkillsPlan) => Promise<void>;
};

/**
 * Checks if an error is a known SPM error
 */
export declare function isSpmError(error: unknown): error is SpmError;

/**
 * List skills in a GitHub repo by cloning and scanning.
 * This avoids GitHub API rate limits.
 */
export declare function listRepoSkills(owner: string, repo: string, ref?: string): Promise<SkillInfo[]>;

/**
 * Error thrown when manifest operations fail
 */
export declare class ManifestError extends SpmError {
    readonly filePath: string;
    constructor(options: {
        code: ErrorCode.MANIFEST_NOT_FOUND | ErrorCode.MANIFEST_EXISTS | ErrorCode.MANIFEST_VALIDATION_ERROR;
        filePath: string;
        message?: string;
        cause?: Error;
    });
}

/**
 * Error thrown when network operations fail
 */
export declare class NetworkError extends SpmError {
    readonly url?: string;
    constructor(options: {
        code: ErrorCode.NETWORK_ERROR | ErrorCode.REPO_NOT_FOUND;
        url?: string;
        message: string;
        cause?: Error;
    });
}

/**
 * Skills manifest output type after validation/default application.
 * Use this for normalized manifests returned from reads/parsing.
 */
declare type NormalizedSkillsManifest = {
    $schema?: string;
    installDir: string;
    linkTargets: string[];
    selfSkill?: boolean;
    skills: Record<string, string>;
    patchedSkills?: Record<string, string>;
};

export declare type NormalizedSpecifier = {
    type: 'git' | 'link' | 'local' | 'file' | 'npm';
    source: string;
    ref: string | null;
    path: string;
    normalized: string;
    skillName: string;
};

export declare function normalizeSkillsManifest(manifest: Partial<SkillsManifest>): NormalizedSkillsManifest;

export declare function normalizeSpecifier(specifier: string, options?: NormalizeSpecifierOptions): NormalizedSpecifier;

declare type NormalizeSpecifierOptions = {
    installDir?: string;
    skillName?: string;
};

/**
 * Error thrown when parsing fails (JSON, YAML, specifiers)
 */
export declare class ParseError extends SpmError {
    readonly filePath?: string;
    readonly content?: string;
    constructor(options: {
        code: ErrorCode.PARSE_ERROR | ErrorCode.JSON_PARSE_ERROR | ErrorCode.YAML_PARSE_ERROR | ErrorCode.INVALID_SPECIFIER;
        filePath?: string;
        content?: string;
        message: string;
        cause?: Error;
    });
}

export declare function parseGitHubUrl(input: string): {
    owner: string;
    repo: string;
} | null;

export declare function parseOwnerRepo(input: string): {
    owner: string;
    repo: string;
} | null;

export declare function parseSpecifier(specifier: string): {
    sourcePart: string;
    ref: string | null;
    path: string;
};

export declare function patchCommand(options: PatchCommandOptions): Promise<PatchCommandResult>;

export declare type PatchCommandOptions = {
    cwd: string;
    skillName: string;
    editDir?: string;
    ignoreExisting?: boolean;
};

export declare type PatchCommandResult = {
    status: 'patched';
    skillName: string;
    editDir: string;
    originalSpecifier: string;
};

export declare function patchCommitCommand(options: PatchCommitCommandOptions): Promise<PatchCommitCommandResult>;

export declare type PatchCommitCommandOptions = {
    cwd: string;
    editDir: string;
    patchesDir?: string;
};

export declare type PatchCommitCommandResult = {
    status: 'patched';
    skillName: string;
    patchFile: string;
};

declare type ProgressReporterOptions = {
    isTTY?: boolean;
    write?: (text: string) => void;
    info?: (text: string) => void;
};

export declare function readSkillsManifest(rootDir: string): Promise<NormalizedSkillsManifest | null>;

export declare type ResolvedSkillEntry = {
    specifier: string;
    resolution: {
        type: 'link';
        path: string;
    } | {
        type: 'local';
        path: string;
    } | {
        type: 'file';
        tarball: string;
        path: string;
    } | {
        type: 'git';
        url: string;
        commit: string;
        path: string;
    } | {
        type: 'npm';
        packageName: string;
        version: string;
        path: string;
        tarball: string;
        integrity?: string;
        registry?: string;
    };
    digest: string;
    patch?: {
        path: string;
        digest: string;
    };
};

export declare type ResolvedSkillsPlan = {
    installDir: string;
    linkTargets: string[];
    skills: Record<string, ResolvedSkillEntry>;
};

export declare function resolveSkillEntry(cwd: string, specifier: string, skillName?: string, options?: {
    installDir?: string;
}): Promise<{
    skillName: string;
    entry: ResolvedSkillEntry;
}>;

export declare function resolveSkillsPlan(cwd: string, manifest: NormalizedSkillsManifest, options?: {
    onProgress?: InstallProgressListener;
}): Promise<ResolvedSkillsPlan>;

export declare function runCli(argv: string[], context?: {
    cwd?: string;
}): Promise<unknown>;

/**
 * Error thrown when a skill operation fails
 */
export declare class SkillError extends SpmError {
    readonly skillName: string;
    constructor(options: {
        code: ErrorCode.SKILL_NOT_FOUND | ErrorCode.SKILL_EXISTS | ErrorCode.VALIDATION_ERROR;
        skillName: string;
        message?: string;
        cause?: Error;
    });
}

export declare type SkillInfo = {
    name: string;
    description: string;
    path: string;
};

/**
 * Skills manifest input type used for authoring/writing manifests.
 * This preserves optionality for fields with defaults.
 */
export declare type SkillsManifest = {
    $schema?: string;
    installDir?: string;
    linkTargets?: string[];
    selfSkill?: boolean;
    skills?: Record<string, string>;
    patchedSkills?: Record<string, string>;
};

/**
 * Base error class for SPM (Skills Package Manager)
 * All custom errors should extend this class
 */
export declare class SpmError extends Error {
    readonly code: ErrorCode;
    readonly cause?: Error;
    readonly context: Record<string, unknown>;
    constructor(options: {
        code: ErrorCode;
        message: string;
        cause?: Error;
        context?: Record<string, unknown>;
    });
    /**
     * Returns a formatted string representation of the error
     */
    toString(): string;
    /**
     * Returns a detailed object representation for logging/debugging
     */
    toJSON(): Record<string, unknown>;
}

export declare function updateCommand(options: UpdateCommandOptions): Promise<UpdateCommandResult>;

export declare type UpdateCommandOptions = {
    cwd: string;
    skills?: string[];
};

export declare type UpdateCommandResult = {
    status: 'updated' | 'skipped' | 'failed';
    updated: string[];
    unchanged: string[];
    skipped: Array<{
        name: string;
        reason: 'link-specifier' | 'local-specifier' | 'file-specifier';
    }>;
    failed: Array<{
        name: string;
        reason: string;
    }>;
};

export declare function writeSkillsManifest(rootDir: string, manifest: SkillsManifest): Promise<void>;

export { }