@joe-sh/pj 1.4.0

package/dist/index.d.cts

@@ -0,0 +1,565 @@
+import { Options } from 'execa';
+
+/**
+ * A discovered project from pj
+ */
+interface Project {
+    /** Absolute path to the project directory */
+    path: string;
+    /** Name of the project (directory name) */
+    name: string;
+    /** The marker file/directory that identified this as a project */
+    marker: string;
+    /** Optional icon for the marker (Nerd Font) */
+    icon: string | undefined;
+    /** Priority of the marker (higher = more specific) */
+    priority: number | undefined;
+}
+/**
+ * Options for project discovery
+ */
+interface DiscoverOptions {
+    /** Paths to search for projects */
+    paths?: string[];
+    /** Project marker files/directories to look for */
+    markers?: string[];
+    /** Patterns to exclude from search */
+    excludes?: string[];
+    /** Maximum directory depth to search */
+    maxDepth?: number;
+    /** Don't respect .gitignore files */
+    noIgnore?: boolean;
+    /** Allow nested project detection */
+    nested?: boolean;
+    /** Bypass cache and do fresh discovery */
+    noCache?: boolean;
+    /** Include icons in output */
+    icons?: boolean;
+    /** Custom config file path */
+    configPath?: string;
+    /** Enable verbose/debug output */
+    verbose?: boolean;
+}
+/**
+ * Configuration for pj
+ */
+interface PjConfig {
+    /** Paths to search for projects */
+    paths: string[];
+    /** Project marker files/directories */
+    markers: string[];
+    /** Patterns to exclude */
+    exclude: string[];
+    /** Maximum search depth */
+    maxDepth: number;
+    /** Cache time-to-live in seconds */
+    cacheTTL: number;
+    /** Don't respect .gitignore */
+    noIgnore: boolean;
+    /** Allow nested projects */
+    noNested: boolean;
+    /** Icon mappings for markers */
+    icons: Record<string, string>;
+}
+/**
+ * Information about the pj cache
+ */
+interface CacheInfo {
+    /** Whether the cache exists */
+    exists: boolean;
+    /** Path to the cache directory */
+    path: string;
+    /** Number of cache files */
+    fileCount: number;
+    /** Total size in bytes */
+    totalSize: number;
+}
+/**
+ * Binary installation status
+ */
+interface BinaryStatus {
+    /** Whether a binary is available */
+    available: boolean;
+    /** Path to the binary */
+    path: string | null;
+    /** Version of the binary */
+    version: string | null;
+    /** Source of the binary: 'global', 'cache', or 'env' */
+    source: "global" | "cache" | "env" | null;
+}
+/**
+ * Options for binary management
+ */
+interface BinaryOptions {
+    /** Force download even if binary exists */
+    force?: boolean;
+    /** Specific version to install (defaults to latest) */
+    version?: string;
+    /** Progress callback for downloads */
+    onProgress?: (progress: DownloadProgress) => void;
+}
+/**
+ * Download progress information
+ */
+interface DownloadProgress {
+    /** Bytes downloaded so far */
+    downloaded: number;
+    /** Total bytes to download (may be undefined if unknown) */
+    total?: number;
+    /** Percentage complete (0-100) */
+    percent?: number;
+}
+/**
+ * GitHub release information
+ */
+interface GithubRelease {
+    /** Release tag name (e.g., "v1.4.1") */
+    tagName: string;
+    /** Release version without 'v' prefix */
+    version: string;
+    /** Release name/title */
+    name: string;
+    /** Whether this is a prerelease */
+    prerelease: boolean;
+    /** Release assets */
+    assets: GithubAsset[];
+}
+/**
+ * GitHub release asset
+ */
+interface GithubAsset {
+    /** Asset name (e.g., "pj_1.4.1_darwin_arm64.tar.gz") */
+    name: string;
+    /** Download URL */
+    downloadUrl: string;
+    /** File size in bytes */
+    size: number;
+    /** Content type */
+    contentType: string;
+}
+/**
+ * Platform information
+ */
+interface Platform {
+    /** Operating system: darwin, linux, win32 */
+    os: "darwin" | "linux" | "win32";
+    /** Architecture: x64, arm64 */
+    arch: "x64" | "arm64";
+    /** pj asset OS name */
+    pjOs: "darwin" | "linux" | "windows";
+    /** pj asset architecture name */
+    pjArch: "amd64" | "arm64";
+}
+/**
+ * Error thrown when binary operations fail
+ */
+declare class PjBinaryError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when pj execution fails
+ */
+declare class PjExecutionError extends Error {
+    readonly exitCode: number | undefined;
+    readonly stderr: string | undefined;
+    constructor(message: string, exitCode?: number, stderr?: string);
+}
+/**
+ * Error thrown when configuration is invalid
+ */
+declare class PjConfigError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+
+/**
+ * Main class for interacting with pj
+ *
+ * Provides a high-level API for project discovery, configuration management,
+ * and binary management.
+ *
+ * @example
+ * ```typescript
+ * const pj = new Pj();
+ *
+ * // Discover all projects
+ * const projects = await pj.discover();
+ *
+ * // Find a specific project
+ * const myProject = await pj.findProject('my-app');
+ *
+ * // Search for projects
+ * const reactProjects = await pj.findProjects(/react/i);
+ * ```
+ */
+declare class Pj {
+    private config;
+    /**
+     * Create a new Pj instance
+     *
+     * @param config - Optional configuration overrides
+     */
+    constructor(config?: Partial<PjConfig>);
+    /**
+     * Discover all projects
+     *
+     * @param options - Discovery options
+     * @returns Array of discovered projects
+     */
+    discover(options?: DiscoverOptions): Promise<Project[]>;
+    /**
+     * Discover projects from specific paths
+     *
+     * Bypasses configured paths and searches only the provided paths.
+     * Useful for integration with other tools.
+     *
+     * @param paths - Paths to search
+     * @param options - Additional discovery options
+     */
+    discoverFromPaths(paths: string[], options?: Omit<DiscoverOptions, "paths">): Promise<Project[]>;
+    /**
+     * Find a project by name
+     *
+     * @param name - Project name to find
+     * @param options - Discovery options
+     */
+    findProject(name: string, options?: DiscoverOptions): Promise<Project | undefined>;
+    /**
+     * Find projects matching a pattern
+     *
+     * @param pattern - String or regex pattern to match
+     * @param options - Discovery options
+     */
+    findProjects(pattern: string | RegExp, options?: DiscoverOptions): Promise<Project[]>;
+    /**
+     * Get projects grouped by marker type
+     *
+     * @param options - Discovery options
+     */
+    discoverByMarker(options?: DiscoverOptions): Promise<Map<string, Project[]>>;
+    /**
+     * Count projects by marker type
+     *
+     * @param options - Discovery options
+     */
+    countByMarker(options?: DiscoverOptions): Promise<Map<string, number>>;
+    /**
+     * Clear the pj project cache
+     */
+    clearCache(): Promise<void>;
+    /**
+     * Get information about the pj cache
+     */
+    getCacheInfo(): Promise<CacheInfo>;
+    /**
+     * Load configuration from file
+     *
+     * @param configPath - Optional path to config file
+     */
+    loadConfig(configPath?: string): Promise<PjConfig>;
+    /**
+     * Save configuration to file
+     *
+     * @param config - Configuration to save (uses current config if not provided)
+     * @param configPath - Optional path to config file
+     */
+    saveConfig(config?: Partial<PjConfig>, configPath?: string): Promise<void>;
+    /**
+     * Get current configuration
+     */
+    getConfig(): PjConfig;
+    /**
+     * Update configuration
+     *
+     * @param config - Partial configuration to merge
+     */
+    setConfig(config: Partial<PjConfig>): void;
+    /**
+     * Ensure the pj binary is available
+     *
+     * Downloads the binary if not already installed.
+     *
+     * @param options - Binary options
+     * @returns Path to the binary
+     */
+    ensureBinary(options?: BinaryOptions): Promise<string>;
+    /**
+     * Get the status of the pj binary
+     */
+    getBinaryStatus(): Promise<BinaryStatus>;
+    /**
+     * Update the pj binary to the latest version
+     *
+     * @param options - Binary options
+     * @returns Path to the updated binary
+     */
+    updateBinary(options?: BinaryOptions): Promise<string>;
+    /**
+     * Get the version of the pj binary
+     */
+    getBinaryVersion(): Promise<string | null>;
+    /**
+     * Merge instance config with provided options
+     */
+    private mergeOptions;
+}
+
+/**
+ * Discover projects using pj
+ */
+declare function discover(options?: DiscoverOptions): Promise<Project[]>;
+/**
+ * Discover projects from specific paths provided via stdin
+ *
+ * This bypasses the configured paths and discovers projects only in the
+ * provided paths. Useful for integrating with other tools that provide
+ * a list of directories to search.
+ */
+declare function discoverFromPaths(paths: string[], options?: Omit<DiscoverOptions, "paths">): Promise<Project[]>;
+/**
+ * Find a project by name
+ */
+declare function findProject(name: string, options?: DiscoverOptions): Promise<Project | undefined>;
+/**
+ * Find projects matching a pattern
+ */
+declare function findProjects(pattern: string | RegExp, options?: DiscoverOptions): Promise<Project[]>;
+/**
+ * Get projects grouped by marker type
+ */
+declare function discoverByMarker(options?: DiscoverOptions): Promise<Map<string, Project[]>>;
+/**
+ * Count projects by marker type
+ */
+declare function countByMarker(options?: DiscoverOptions): Promise<Map<string, number>>;
+
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: PjConfig;
+/**
+ * Load pj configuration from file
+ */
+declare function loadConfig(configPath?: string): Promise<PjConfig>;
+/**
+ * Save configuration to file
+ */
+declare function saveConfig(config: Partial<PjConfig>, configPath?: string): Promise<void>;
+/**
+ * Check if a config file exists
+ */
+declare function configExists(configPath?: string): Promise<boolean>;
+/**
+ * Get the default config path
+ */
+declare function getConfigPath(): string;
+/**
+ * Expand ~ in paths to home directory
+ */
+declare function expandPath(p: string): string;
+/**
+ * Expand all paths in config
+ */
+declare function expandConfigPaths(config: PjConfig): PjConfig;
+
+/**
+ * Clear the pj project cache
+ */
+declare function clearCache(): Promise<void>;
+/**
+ * Get information about the pj cache
+ */
+declare function getCacheInfo(): Promise<CacheInfo>;
+/**
+ * Get the cache directory path
+ */
+declare function getCachePath(): string;
+
+/**
+ * Manages the pj binary installation and updates
+ *
+ * Note: This module uses `execa` for process execution which does NOT use shell
+ * by default, preventing command injection vulnerabilities.
+ */
+declare class BinaryManager {
+    private cachedBinaryPath;
+    /**
+     * Get the path to the pj binary, downloading if necessary
+     */
+    getBinaryPath(options?: BinaryOptions): Promise<string>;
+    /**
+     * Get the current binary status
+     */
+    getStatus(): Promise<BinaryStatus>;
+    /**
+     * Download and install the pj binary.
+     * If no specific version is requested, downloads the highest compatible version
+     * within the target major.minor range.
+     */
+    downloadBinary(options?: BinaryOptions): Promise<string>;
+    /**
+     * Update the binary to the highest compatible version within the target range.
+     */
+    updateBinary(options?: BinaryOptions): Promise<string>;
+    /**
+     * Get the version of a pj binary
+     */
+    getVersion(binaryPath: string): Promise<string | null>;
+    /**
+     * Check if a binary path is a valid pj binary
+     */
+    isValidBinary(binaryPath: string): Promise<boolean>;
+    /**
+     * Find the globally installed pj binary.
+     * Only returns the binary if it's version-compatible with our target.
+     */
+    private findGlobalBinary;
+    /**
+     * Get the path to the cached binary if it exists and is version-compatible.
+     */
+    private getCachedBinaryPath;
+    /**
+     * Check if we should check for updates
+     */
+    private shouldCheckForUpdate;
+    /**
+     * Get cached metadata
+     */
+    private getMetadata;
+    /**
+     * Save metadata to cache
+     */
+    private saveMetadata;
+    /**
+     * Get all releases from GitHub (up to 100 most recent)
+     */
+    getAllReleases(): Promise<GithubRelease[]>;
+    /**
+     * Get the highest compatible release within the target major.minor range.
+     */
+    getCompatibleRelease(): Promise<GithubRelease>;
+    /**
+     * Get the latest release from GitHub
+     */
+    getLatestRelease(): Promise<GithubRelease>;
+    /**
+     * Get a specific release from GitHub
+     */
+    private getRelease;
+    /**
+     * Parse GitHub release response
+     */
+    private parseRelease;
+    /**
+     * Download an asset to a file
+     */
+    private downloadAsset;
+    /**
+     * Clear the binary cache
+     */
+    clearCache(): Promise<void>;
+}
+/**
+ * Get the singleton BinaryManager instance
+ */
+declare function getBinaryManager(): BinaryManager;
+
+/**
+ * Detect the current platform and return normalized platform info
+ */
+declare function detectPlatform(): Platform;
+/**
+ * Get the expected asset filename for the current platform
+ */
+declare function getAssetFilename(version: string, platform?: Platform): string;
+/**
+ * Check if the current platform is supported
+ */
+declare function isPlatformSupported(): boolean;
+
+/**
+ * Target pj version (major.minor) that this package is compatible with.
+ * The installer will accept any patch version within this range.
+ * Example: "1.4" means pj 1.4.0, 1.4.1, 1.4.2, etc. are all compatible.
+ *
+ * IMPORTANT: When pj releases a new minor version (e.g., 1.5.0),
+ * this package must also release a new minor version to match.
+ */
+declare const PJ_TARGET_VERSION = "1.4";
+/** GitHub repository owner */
+declare const GITHUB_OWNER = "josephschmitt";
+/** GitHub repository name */
+declare const GITHUB_REPO = "pj";
+/** Get the appropriate binary name for the current platform */
+declare function getBinaryName(): string;
+/** Cache directory for pj-node */
+declare function getCacheDir(): string;
+/** Binary cache directory */
+declare function getBinaryCacheDir(): string;
+
+/**
+ * Parsed semantic version
+ */
+interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    raw: string;
+}
+/**
+ * Parse a semantic version string
+ */
+declare function parseVersion(version: string): ParsedVersion | null;
+/**
+ * Parse a major.minor version target (e.g., "1.4")
+ */
+declare function parseTargetVersion(target: string): {
+    major: number;
+    minor: number;
+} | null;
+/**
+ * Check if a version is compatible with the target major.minor version.
+ * A version is compatible if it has the same major.minor version.
+ *
+ * Example: target "1.4" is compatible with "1.4.0", "1.4.1", "1.4.99"
+ *          but NOT with "1.3.0", "1.5.0", or "2.4.0"
+ */
+declare function isVersionCompatible(version: string, target?: string): boolean;
+/**
+ * Compare two versions. Returns:
+ * - negative if a < b
+ * - positive if a > b
+ * - 0 if a === b
+ */
+declare function compareVersions(a: string, b: string): number;
+/**
+ * Find the highest compatible version from a list of versions
+ */
+declare function findHighestCompatibleVersion(versions: string[], target?: string): string | null;
+
+/**
+ * Result from executing pj
+ */
+interface PjResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Build command-line arguments from DiscoverOptions
+ */
+declare function buildArgs(options?: DiscoverOptions): string[];
+/**
+ * Parse JSON output from pj
+ */
+declare function parseJsonOutput(output: string): Project[];
+/**
+ * Execute the pj binary with the given arguments
+ *
+ * Note: This function uses `execa` which does NOT use shell by default,
+ * preventing command injection vulnerabilities.
+ */
+declare function executePj(args: string[], execaOptions?: Options): Promise<PjResult>;
+
+export { BinaryManager, type BinaryOptions, type BinaryStatus, type CacheInfo, DEFAULT_CONFIG, type DiscoverOptions, type DownloadProgress, GITHUB_OWNER, GITHUB_REPO, type GithubAsset, type GithubRelease, PJ_TARGET_VERSION, type ParsedVersion, Pj, PjBinaryError, type PjConfig, PjConfigError, PjExecutionError, type PjResult, type Platform, type Project, buildArgs, clearCache, compareVersions, configExists, countByMarker, detectPlatform, discover, discoverByMarker, discoverFromPaths, executePj, expandConfigPaths, expandPath, findHighestCompatibleVersion, findProject, findProjects, getAssetFilename, getBinaryCacheDir, getBinaryManager, getBinaryName, getCacheDir, getCacheInfo, getCachePath, getConfigPath, isPlatformSupported, isVersionCompatible, loadConfig, parseJsonOutput, parseTargetVersion, parseVersion, saveConfig };