@offworld/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1008 @@
+import { Agent, Config, Config as Config$1, FileIndex, FileIndexEntry, FileRole, GlobalMap, GlobalMap as GlobalMap$1, GlobalMapRepoEntry, GlobalMapRepoEntry as GlobalMapRepoEntry$1, ProjectMap, ProjectMap as ProjectMap$1, ProjectMapRepoEntry, ProjectMapRepoEntry as ProjectMapRepoEntry$1, RemoteRepoSource, RepoSource, RepoSource as RepoSource$1 } from "@offworld/types";
+
+//#region src/constants.d.ts
+/**
+ * SDK Constants
+ */
+/** SDK version - must match package.json */
+declare const VERSION = "0.1.0";
+/**
+ * Default patterns to ignore when scanning repositories.
+ * Includes directories, binary files, IDE configs, and build outputs.
+ */
+declare const DEFAULT_IGNORE_PATTERNS: readonly [".git", ".git/**", ".svn", ".hg", "node_modules", "node_modules/**", "vendor", "vendor/**", ".pnpm", ".yarn", "dist", "dist/**", "build", "build/**", "out", "out/**", ".next", ".nuxt", ".output", "target", "__pycache__", "*.pyc", ".vscode", ".vscode/**", ".idea", ".idea/**", "*.swp", "*.swo", ".DS_Store", "*.jpg", "*.jpeg", "*.png", "*.gif", "*.ico", "*.webp", "*.svg", "*.bmp", "*.tiff", "*.mp4", "*.webm", "*.mov", "*.avi", "*.mkv", "*.mp3", "*.wav", "*.flac", "*.ogg", "*.pdf", "*.zip", "*.tar", "*.gz", "*.rar", "*.7z", "*.exe", "*.dll", "*.so", "*.dylib", "*.bin", "*.wasm", "*.woff", "*.woff2", "*.ttf", "*.eot", "*.otf", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb", "Cargo.lock", "Gemfile.lock", "poetry.lock", "composer.lock", "go.sum", "coverage", "coverage/**", ".nyc_output", ".coverage", "htmlcov", "*.log", "logs", "tmp", "temp", ".tmp", ".temp", ".cache", ".env", ".env.*", "*.pem", "*.key"];
+//#endregion
+//#region src/config.d.ts
+/**
+ * Returns the repository root directory.
+ * Uses configured repoRoot or defaults to ~/ow
+ */
+declare function getMetaRoot(): string;
+declare function getRepoRoot(config?: Config$1): string;
+/**
+ * Returns the path for a specific repository.
+ * Format: {repoRoot}/{provider}/{owner}/{repo}
+ *
+ * @param fullName - The repo identifier in "owner/repo" format
+ * @param provider - Git provider (defaults to "github")
+ * @param config - Optional config for custom repoRoot
+ */
+declare function getRepoPath(fullName: string, provider?: "github" | "gitlab" | "bitbucket", config?: Config$1): string;
+/**
+ * Convert owner/repo format to meta directory name.
+ * Collapses owner==repo (e.g., better-auth/better-auth -> better-auth)
+ */
+declare function toMetaDirName(repoName: string): string;
+/**
+ * Convert owner/repo format to reference filename.
+ * Collapses redundant owner/repo pairs by checking if repo name is contained in owner:
+ * - honojs/hono -> hono.md (hono is in honojs)
+ * - get-convex/convex-backend -> convex-backend.md (convex is in get-convex)
+ * - tanstack/query -> tanstack-query.md (query is not in tanstack)
+ */
+declare function toReferenceFileName(repoName: string): string;
+declare function toReferenceName(repoName: string): string;
+declare function getReferencePath(fullName: string): string;
+declare function getMetaPath(fullName: string): string;
+/**
+ * Returns the path to the configuration file
+ * Uses XDG Base Directory specification
+ */
+declare function getConfigPath(): string;
+/**
+ * Loads configuration from ~/.config/offworld/offworld.json
+ * Returns defaults if file doesn't exist
+ */
+declare function loadConfig(): Config$1;
+/**
+ * Saves configuration to ~/.config/offworld/offworld.json
+ * Creates directory if it doesn't exist
+ * Merges with existing config
+ */
+declare function saveConfig(updates: Partial<Config$1>): Config$1;
+//#endregion
+//#region src/paths.d.ts
+/**
+ * XDG-based directory paths for offworld CLI
+ * Uses xdg-basedir package for cross-platform compatibility (Linux/macOS)
+ */
+/**
+ * Main namespace for all XDG-compliant paths
+ */
+declare const Paths: {
+  /**
+   * XDG_CONFIG_HOME/offworld
+   * Fallback: ~/.config/offworld
+   */
+  readonly config: string;
+  /**
+   * XDG_DATA_HOME/offworld
+   * Fallback: ~/.local/share/offworld
+   */
+  readonly data: string;
+  /**
+   * XDG_STATE_HOME/offworld
+   * Fallback: ~/.local/state/offworld
+   */
+  readonly state: string;
+  /**
+   * Configuration file path: ~/.config/offworld/offworld.json
+   */
+  readonly configFile: string;
+  /**
+   * Auth file path: ~/.local/share/offworld/auth.json
+   */
+  readonly authFile: string;
+  /**
+   * Meta directory: ~/.local/share/offworld/meta
+   */
+  readonly metaDir: string;
+  /**
+   * Default repo root: ~/ow
+   */
+  readonly defaultRepoRoot: string;
+  /**
+   * Offworld single-skill directory: ~/.local/share/offworld/skill/offworld
+   */
+  readonly offworldSkillDir: string;
+  /**
+   * Offworld references directory: ~/.local/share/offworld/skill/offworld/references
+   */
+  readonly offworldReferencesDir: string;
+  /**
+   * Offworld assets directory: ~/.local/share/offworld/skill/offworld/assets
+   */
+  readonly offworldAssetsDir: string;
+  /**
+   * Global map path: ~/.local/share/offworld/skill/offworld/assets/map.json
+   */
+  readonly offworldGlobalMapPath: string;
+};
+/**
+ * Expands ~ to user's home directory (for backward compatibility)
+ */
+declare function expandTilde(path: string): string;
+//#endregion
+//#region src/repo-source.d.ts
+declare class RepoSourceError extends Error {
+  constructor(message: string);
+}
+declare class PathNotFoundError extends RepoSourceError {
+  constructor(path: string);
+}
+declare class NotGitRepoError extends RepoSourceError {
+  constructor(path: string);
+}
+/**
+ * Parses a repository input and returns a structured RepoSource
+ *
+ * Supported formats:
+ * - owner/repo (short format, defaults to GitHub)
+ * - https://github.com/owner/repo
+ * - https://gitlab.com/owner/repo
+ * - https://bitbucket.org/owner/repo
+ * - git@github.com:owner/repo.git (SSH format)
+ * - . (current directory as local repo)
+ * - /absolute/path (local repo)
+ *
+ * @throws PathNotFoundError if local path doesn't exist
+ * @throws NotGitRepoError if local path is not a git repository
+ * @throws RepoSourceError for other parsing failures
+ */
+declare function parseRepoInput(input: string): RepoSource$1;
+declare function getReferenceFileNameForSource(source: RepoSource$1): string;
+//#endregion
+//#region src/index-manager.d.ts
+/**
+ * Reads the global map from ~/.local/share/offworld/skill/offworld/assets/map.json
+ * Returns empty map if file doesn't exist or is invalid
+ */
+declare function readGlobalMap(): GlobalMap$1;
+/**
+ * Writes the global map to ~/.local/share/offworld/skill/offworld/assets/map.json
+ * Creates directory if it doesn't exist
+ */
+declare function writeGlobalMap(map: GlobalMap$1): void;
+/**
+ * Adds or updates a repo entry in the global map
+ *
+ * @param qualifiedName - The qualified repo name (owner/repo)
+ * @param entry - The map entry to add/update
+ */
+declare function upsertGlobalMapEntry(qualifiedName: string, entry: GlobalMapRepoEntry$1): void;
+/**
+ * Removes a repo entry from the global map
+ *
+ * @param qualifiedName - The qualified repo name (owner/repo)
+ * @returns true if repo was removed, false if not found
+ */
+declare function removeGlobalMapEntry(qualifiedName: string): boolean;
+/**
+ * Writes a project map to ./.offworld/map.json
+ *
+ * @param projectRoot - Absolute path to project root
+ * @param entries - Map of qualified repo names to project map entries
+ */
+declare function writeProjectMap(projectRoot: string, entries: Record<string, ProjectMapRepoEntry$1>): void;
+//#endregion
+//#region src/map.d.ts
+interface MapEntry {
+  scope: "project" | "global";
+  qualifiedName: string;
+  entry: GlobalMapRepoEntry$1 | ProjectMapRepoEntry$1;
+}
+interface SearchResult {
+  qualifiedName: string;
+  fullName: string;
+  localPath: string;
+  primary: string;
+  keywords: string[];
+  score: number;
+}
+interface GetMapEntryOptions {
+  preferProject?: boolean;
+  cwd?: string;
+}
+interface SearchMapOptions {
+  limit?: number;
+  cwd?: string;
+}
+/**
+ * Resolve an input string to a qualified repo key in a map.
+ *
+ * @param input - Accepts github.com:owner/repo, owner/repo, or repo name
+ * @param map - A global or project map
+ * @returns The matching qualified name or null
+ */
+declare function resolveRepoKey(input: string, map: GlobalMap$1 | ProjectMap$1): string | null;
+/**
+ * Get a map entry for a repo, preferring project map if available.
+ *
+ * @param input - Repo identifier (github.com:owner/repo, owner/repo, or repo)
+ * @param options - Options for lookup
+ * @returns Entry with scope and qualified name, or null if not found
+ */
+declare function getMapEntry(input: string, options?: GetMapEntryOptions): MapEntry | null;
+/**
+ * Search the map for repos matching a term.
+ *
+ * Scoring:
+ * - Exact fullName match: 100
+ * - Keyword hit: 50 per keyword
+ * - Partial contains in fullName: 25
+ * - Partial contains in keywords: 10
+ *
+ * @param term - Search term
+ * @param options - Search options
+ * @returns Sorted list of matches
+ */
+declare function searchMap(term: string, options?: SearchMapOptions): SearchResult[];
+/**
+ * Get the project map path if it exists in cwd.
+ */
+declare function getProjectMapPath(cwd?: string): string | null;
+//#endregion
+//#region src/clone.d.ts
+declare class CloneError extends Error {
+  constructor(message: string);
+}
+declare class RepoExistsError extends CloneError {
+  constructor(path: string);
+}
+declare class RepoNotFoundError extends CloneError {
+  constructor(qualifiedName: string);
+}
+declare class GitError extends CloneError {
+  readonly command: string;
+  readonly exitCode: number | null;
+  constructor(message: string, command: string, exitCode: number | null);
+}
+interface CloneOptions {
+  /** Use shallow clone (--depth 1) */
+  shallow?: boolean;
+  /** Clone specific branch */
+  branch?: string;
+  /** Custom config for repo root path */
+  config?: Config$1;
+  /** Force clone even if directory exists (removes existing) */
+  force?: boolean;
+  /** Use sparse checkout for large repos (only src/, lib/, packages/, docs/) */
+  sparse?: boolean;
+}
+/**
+ * Get the current commit SHA for a repository
+ */
+declare function getCommitSha(repoPath: string): string;
+/**
+ * Get the number of commits between two SHAs.
+ * Returns the number of commits from `olderSha` to `newerSha`.
+ * Returns null if the distance cannot be determined (e.g., shallow clone without the commit).
+ *
+ * @param repoPath - Path to the git repository
+ * @param olderSha - The older commit SHA (e.g., remote skill's commit)
+ * @param newerSha - The newer commit SHA (e.g., current HEAD), defaults to HEAD
+ */
+declare function getCommitDistance(repoPath: string, olderSha: string, newerSha?: string): number | null;
+/**
+ * Clone a remote repository to the local repo root.
+ *
+ * @param source - Remote repo source from parseRepoInput()
+ * @param options - Clone options (shallow, branch, config)
+ * @returns The local path where the repo was cloned
+ * @throws RepoExistsError if repo already exists (unless force is true)
+ * @throws GitError if clone fails
+ */
+declare function cloneRepo(source: RemoteRepoSource, options?: CloneOptions): Promise<string>;
+/**
+ * Check if a repository is a shallow clone.
+ */
+declare function isShallowClone(repoPath: string): boolean;
+/**
+ * Convert a shallow clone to a full clone by fetching all history.
+ * Returns true if the repo was shallow and is now unshallowed.
+ * Returns false if the repo was already a full clone.
+ */
+declare function unshallowRepo(repoPath: string): Promise<boolean>;
+interface UpdateResult {
+  /** Whether any updates were fetched */
+  updated: boolean;
+  /** Previous commit SHA before update */
+  previousSha: string;
+  /** Current commit SHA after update */
+  currentSha: string;
+  /** Whether the repo was unshallowed */
+  unshallowed?: boolean;
+}
+interface UpdateOptions {
+  /** Convert shallow clone to full clone */
+  unshallow?: boolean;
+}
+/**
+ * Update a cloned repository by running git fetch and pull.
+ *
+ * @param qualifiedName - The qualified name of the repo (e.g., "github.com:owner/repo")
+ * @param options - Update options
+ * @returns Update result with commit SHAs
+ * @throws RepoNotFoundError if repo not in index
+ * @throws GitError if fetch/pull fails
+ */
+declare function updateRepo(qualifiedName: string, options?: UpdateOptions): Promise<UpdateResult>;
+interface RemoveOptions {
+  /** Only remove reference files (keep cloned repo) */
+  referenceOnly?: boolean;
+  /** Only remove cloned repo (keep reference files) */
+  repoOnly?: boolean;
+}
+/**
+ * Remove a cloned repository and its reference data.
+ *
+ * @param qualifiedName - The qualified name of the repo
+ * @param options - Remove options
+ * @returns true if removed, false if not found
+ */
+declare function removeRepo(qualifiedName: string, options?: RemoveOptions): Promise<boolean>;
+/**
+ * List all cloned repositories from the global map.
+ *
+ * @returns Array of qualified names
+ */
+declare function listRepos(): string[];
+/**
+ * Check if a repository is cloned and in the map.
+ *
+ * @param qualifiedName - The qualified name of the repo
+ * @returns true if repo exists in map and on disk
+ */
+declare function isRepoCloned(qualifiedName: string): boolean;
+/**
+ * Get the local path for a cloned repository.
+ *
+ * @param qualifiedName - The qualified name of the repo
+ * @returns The local path or undefined if not cloned
+ */
+declare function getClonedRepoPath(qualifiedName: string): string | undefined;
+//#endregion
+//#region src/ai/opencode.d.ts
+interface StreamPromptOptions {
+  prompt: string;
+  cwd: string;
+  systemPrompt?: string;
+  provider?: string;
+  model?: string;
+  /** Timeout in milliseconds. Set to 0 or undefined for no timeout. */
+  timeoutMs?: number;
+  onDebug?: (message: string) => void;
+  onStream?: (text: string) => void;
+}
+interface StreamPromptResult {
+  text: string;
+  sessionId: string;
+  durationMs: number;
+}
+declare function streamPrompt(options: StreamPromptOptions): Promise<StreamPromptResult>;
+//#endregion
+//#region src/ai/errors.d.ts
+/**
+ * Base class for OpenCode reference errors
+ */
+declare class OpenCodeReferenceError extends Error {
+  readonly details?: unknown | undefined;
+  readonly _tag: string;
+  constructor(message: string, details?: unknown | undefined);
+}
+/**
+ * Error when the @opencode-ai/sdk package is not installed
+ */
+declare class OpenCodeSDKError extends OpenCodeReferenceError {
+  readonly _tag: "OpenCodeSDKError";
+  constructor();
+}
+//#endregion
+//#region src/sync.d.ts
+declare class SyncError extends Error {
+  constructor(message: string);
+}
+declare class NetworkError extends SyncError {
+  readonly statusCode?: number | undefined;
+  constructor(message: string, statusCode?: number | undefined);
+}
+declare class AuthenticationError extends SyncError {
+  constructor(message?: string);
+}
+declare class RateLimitError extends SyncError {
+  constructor(message?: string);
+}
+declare class ConflictError extends SyncError {
+  readonly remoteCommitSha?: string | undefined;
+  constructor(message?: string, remoteCommitSha?: string | undefined);
+}
+declare class CommitExistsError extends SyncError {
+  constructor(message?: string);
+}
+declare class InvalidInputError extends SyncError {
+  constructor(message: string);
+}
+declare class InvalidReferenceError extends SyncError {
+  constructor(message: string);
+}
+declare class RepoNotFoundError$1 extends SyncError {
+  constructor(message?: string);
+}
+declare class LowStarsError extends SyncError {
+  constructor(message?: string);
+}
+declare class PrivateRepoError extends SyncError {
+  constructor(message?: string);
+}
+declare class CommitNotFoundError extends SyncError {
+  constructor(message?: string);
+}
+declare class GitHubError extends SyncError {
+  constructor(message?: string);
+}
+declare class PushNotAllowedError extends SyncError {
+  readonly reason: "local" | "not-github";
+  constructor(message: string, reason: "local" | "not-github");
+}
+/** Reference data structure for sync operations */
+interface ReferenceData {
+  fullName: string;
+  referenceName: string;
+  referenceDescription: string;
+  referenceContent: string;
+  commitSha: string;
+  generatedAt: string;
+}
+/** Response from pull query */
+interface PullResponse {
+  fullName: string;
+  referenceName: string;
+  referenceDescription: string;
+  referenceContent: string;
+  commitSha: string;
+  generatedAt: string;
+}
+/** Response from check query */
+interface CheckResponse {
+  exists: boolean;
+  commitSha?: string;
+  generatedAt?: string;
+}
+/** Response from push mutation */
+interface PushResponse {
+  success: boolean;
+  message?: string;
+}
+/** Staleness check result */
+interface StalenessResult {
+  isStale: boolean;
+  localCommitSha?: string;
+  remoteCommitSha?: string;
+}
+/** Can push result */
+interface CanPushResult {
+  allowed: boolean;
+  reason?: string;
+  stars?: number;
+}
+/**
+ * Fetches reference from the remote server
+ * @param fullName - Repository full name (owner/repo)
+ * @returns Reference data or null if not found
+ */
+declare function pullReference(fullName: string): Promise<PullResponse | null>;
+/**
+ * Fetches a specific reference by name from the remote server
+ * @param fullName - Repository full name (owner/repo)
+ * @param referenceName - Specific reference name to pull
+ * @returns Reference data or null if not found
+ */
+declare function pullReferenceByName(fullName: string, referenceName: string): Promise<PullResponse | null>;
+/**
+ * Pushes reference to the remote server
+ * All validation happens server-side
+ * @param reference - Reference data to push
+ * @param token - Authentication token
+ * @returns Push result
+ */
+declare function pushReference(reference: ReferenceData, token: string): Promise<PushResponse>;
+/**
+ * Checks if reference exists on remote server (lightweight check)
+ * @param fullName - Repository full name (owner/repo)
+ * @returns Check result
+ */
+declare function checkRemote(fullName: string): Promise<CheckResponse>;
+/**
+ * Checks if a specific reference exists on the remote server
+ * @param fullName - Repository full name (owner/repo)
+ * @param referenceName - Specific reference name to check
+ * @returns Check result
+ */
+declare function checkRemoteByName(fullName: string, referenceName: string): Promise<CheckResponse>;
+/**
+ * Compares local vs remote commit SHA to check staleness
+ * @param fullName - Repository full name (owner/repo)
+ * @param localCommitSha - Local commit SHA
+ * @returns Staleness result
+ */
+declare function checkStaleness(fullName: string, localCommitSha: string): Promise<StalenessResult>;
+/** GitHub repository metadata */
+interface GitHubRepoMetadata {
+  stars: number;
+  description?: string;
+  language?: string;
+  defaultBranch: string;
+}
+/**
+ * Fetches GitHub repository metadata
+ * @param owner - Repository owner
+ * @param repo - Repository name
+ * @returns Repository metadata or null on error
+ */
+declare function fetchGitHubMetadata(owner: string, repo: string): Promise<GitHubRepoMetadata | null>;
+/**
+ * Fetches GitHub repository stars
+ * @param owner - Repository owner
+ * @param repo - Repository name
+ * @returns Number of stars, or 0 on error
+ */
+declare function fetchRepoStars(owner: string, repo: string): Promise<number>;
+/**
+ * Checks if a repository can be pushed to offworld.sh (client-side quick checks)
+ * Note: Star count and other validations happen server-side
+ *
+ * @param source - Repository source
+ * @returns Can push result
+ */
+declare function canPushToWeb(source: RepoSource$1): CanPushResult;
+/**
+ * Validates that a source can be pushed and throws appropriate error if not
+ * Note: This only does quick client-side checks. Full validation happens server-side.
+ * @param source - Repository source
+ * @throws PushNotAllowedError if push is not allowed
+ */
+declare function validatePushAllowed(source: RepoSource$1): void;
+//#endregion
+//#region src/auth.d.ts
+/**
+ * Authentication utilities for offworld CLI
+ */
+/** Stored authentication data */
+interface AuthData {
+  token: string;
+  expiresAt?: string;
+  workosId?: string;
+  refreshToken?: string;
+  email?: string;
+}
+/** Authentication status */
+interface AuthStatus {
+  isLoggedIn: boolean;
+  email?: string;
+  workosId?: string;
+  expiresAt?: string;
+}
+declare class AuthError extends Error {
+  constructor(message: string);
+}
+declare class NotLoggedInError extends AuthError {
+  constructor(message?: string);
+}
+declare class TokenExpiredError extends AuthError {
+  constructor(message?: string);
+}
+/**
+ * Returns the auth file path using XDG Base Directory spec
+ * Location: ~/.local/share/offworld/auth.json
+ */
+declare function getAuthPath(): string;
+/**
+ * Saves authentication data to ~/.local/share/offworld/auth.json
+ * Creates directory if it doesn't exist
+ */
+declare function saveAuthData(data: AuthData): void;
+/**
+ * Loads authentication data from ~/.local/share/offworld/auth.json
+ * Returns null if file doesn't exist or is invalid
+ */
+declare function loadAuthData(): AuthData | null;
+/**
+ * Clears stored authentication data
+ * @returns true if auth file was deleted, false if it didn't exist
+ */
+declare function clearAuthData(): boolean;
+/**
+ * Gets the current authentication token
+ * Auto-refreshes if token expires within 1 minute
+ * @throws NotLoggedInError if not logged in
+ * @throws TokenExpiredError if token is expired and refresh fails
+ */
+declare function getToken(): Promise<string>;
+/**
+ * Gets the current authentication token, or null if not logged in
+ * Does not throw errors
+ */
+declare function getTokenOrNull(): Promise<string | null>;
+/**
+ * Checks if user is logged in with valid token
+ */
+declare function isLoggedIn(): Promise<boolean>;
+declare function getAuthStatus(): Promise<AuthStatus>;
+/**
+ * Refreshes the access token using the stored refresh token
+ * @returns New auth data with refreshed token
+ * @throws AuthError if refresh fails
+ */
+declare function refreshAccessToken(): Promise<AuthData>;
+//#endregion
+//#region src/generate.d.ts
+/**
+ * Simplified AI-only reference generation
+ *
+ * This module provides a streamlined approach to generating reference files
+ * by delegating all codebase exploration to the AI agent via OpenCode.
+ */
+interface GenerateReferenceOptions {
+  /** AI provider ID (e.g., "anthropic", "openai"). Defaults to config value. */
+  provider?: string;
+  /** AI model ID. Defaults to config value. */
+  model?: string;
+  /** Debug callback for detailed logging */
+  onDebug?: (message: string) => void;
+  /** Stream callback for real-time AI output */
+  onStream?: (text: string) => void;
+}
+interface GenerateReferenceResult {
+  /** The generated reference markdown content */
+  referenceContent: string;
+  /** The commit SHA at the time of generation */
+  commitSha: string;
+}
+interface InstallReferenceMeta {
+  /** ISO timestamp when the reference was generated */
+  referenceUpdatedAt: string;
+  /** Git commit SHA at time of generation */
+  commitSha: string;
+  /** SDK version used for generation */
+  version: string;
+}
+/**
+ * Generate a reference markdown file for a repository using AI.
+ *
+ * Opens an OpenCode session and instructs the AI agent to explore the codebase
+ * using Read, Grep, and Glob tools, then produce a comprehensive reference.
+ *
+ * @param repoPath - Path to the repository to analyze
+ * @param repoName - Qualified name of the repo (e.g., "tanstack/query" or "my-local-repo")
+ * @param options - Generation options (provider, model, callbacks)
+ * @returns The generated reference content and commit SHA
+ */
+declare function generateReferenceWithAI(repoPath: string, repoName: string, options?: GenerateReferenceOptions): Promise<GenerateReferenceResult>;
+/**
+ * Ensures the global SKILL.md exists and symlinks the offworld/ directory to all agent skill directories.
+ *
+ * Creates:
+ * - ~/.local/share/offworld/skill/offworld/SKILL.md (static routing template)
+ * - ~/.local/share/offworld/skill/offworld/assets/ (for map.json)
+ * - ~/.local/share/offworld/skill/offworld/references/ (for reference files)
+ * - Symlinks entire offworld/ directory to each agent's skill directory
+ */
+declare function installGlobalSkill(): void;
+/**
+ * Install a reference file for a specific repository.
+ *
+ * Creates:
+ * - ~/.local/share/offworld/skill/offworld/references/{owner-repo}.md
+ * - ~/.local/share/offworld/meta/{owner-repo}/meta.json
+ * - Updates global map with reference info
+ *
+ * @param qualifiedName - Qualified key for map storage (e.g., "github.com:owner/repo" or "local:name")
+ * @param fullName - Full repo name for file naming (e.g., "owner/repo")
+ * @param localPath - Absolute path to the cloned repository
+ * @param referenceContent - The generated reference markdown content
+ * @param meta - Metadata about the generation (referenceUpdatedAt, commitSha, version)
+ * @param keywords - Optional array of keywords for search/routing
+ */
+declare function installReference(qualifiedName: string, fullName: string, localPath: string, referenceContent: string, meta: InstallReferenceMeta, keywords?: string[]): void;
+//#endregion
+//#region src/agents.d.ts
+interface AgentConfig {
+  /** Agent identifier (matches AgentSchema enum) */
+  name: Agent;
+  /** Human-readable name for display */
+  displayName: string;
+  /** Project-level skill directory (relative path) */
+  skillsDir: string;
+  /** User-level skill directory (absolute with ~) */
+  globalSkillsDir: string;
+  /** Check if this agent is installed on the system */
+  detectInstalled: () => boolean;
+}
+declare const agents: Record<Agent, AgentConfig>;
+/**
+ * Detect which agents are installed on the system.
+ * Checks for the existence of each agent's config directory.
+ *
+ * @returns Array of installed agent identifiers
+ */
+declare function detectInstalledAgents(): Agent[];
+/**
+ * Get the configuration for a specific agent.
+ *
+ * @param type - Agent identifier
+ * @returns AgentConfig for the specified agent
+ */
+declare function getAgentConfig(type: Agent): AgentConfig;
+/**
+ * Get all agent configurations as an array.
+ *
+ * @returns Array of all agent configurations
+ */
+declare function getAllAgentConfigs(): AgentConfig[];
+//#endregion
+//#region src/manifest.d.ts
+/**
+ * Dependency manifest parsing for multiple package ecosystems
+ */
+type ManifestType = "npm" | "python" | "rust" | "go" | "unknown";
+interface Dependency {
+  name: string;
+  version?: string;
+  dev: boolean;
+}
+/**
+ * Detects the manifest type in a directory
+ */
+declare function detectManifestType(dir: string): ManifestType;
+/**
+ * Parses dependencies from manifest files
+ */
+declare function parseDependencies(dir: string): Dependency[];
+//#endregion
+//#region src/dep-mappings.d.ts
+/**
+ * Three-tier dependency name to GitHub repo resolution:
+ * 1. KNOWN_MAPPINGS - hardcoded popular packages
+ * 2. npm registry fallback
+ * 3. User prompt (handled by caller)
+ */
+type ResolvedDep = {
+  dep: string;
+  repo: string | null;
+  source: "known" | "npm" | "unknown";
+};
+/**
+ * Hardcoded mappings for popular packages.
+ * Covers top ecosystems: React, Vue, Svelte, backend, database, validation, styling.
+ */
+declare const KNOWN_MAPPINGS: Record<string, string>;
+/**
+ * Fallback to npm registry to extract repository.url.
+ * Returns null if package not found, no repo field, or not a GitHub repo.
+ */
+declare function resolveFromNpm(packageName: string): Promise<string | null>;
+/**
+ * Three-tier resolution:
+ * 1. Check KNOWN_MAPPINGS
+ * 2. Query npm registry
+ * 3. Return unknown (caller prompts user)
+ */
+declare function resolveDependencyRepo(dep: string): Promise<ResolvedDep>;
+//#endregion
+//#region src/reference-matcher.d.ts
+type ReferenceStatus = "installed" | "available" | "generate" | "unknown";
+interface ReferenceMatch {
+  /** Dependency name */
+  dep: string;
+  /** GitHub repo (owner/repo) or null if unknown */
+  repo: string | null;
+  /** Reference availability status */
+  status: ReferenceStatus;
+  /** Resolution source: 'known' | 'npm' | 'unknown' */
+  source: "known" | "npm" | "unknown";
+}
+/**
+ * Check if a reference is installed locally.
+ * A reference is considered installed if {owner-repo}.md exists in offworld/references/.
+ *
+ * @param repo - Repo name in owner/repo format
+ * @returns true if reference is installed locally
+ */
+declare function isReferenceInstalled(repo: string): boolean;
+/**
+ * Match dependencies to their reference availability status.
+ *
+ * Status logic:
+ * - installed: {owner-repo}.md exists in offworld/references/
+ * - available: Has valid GitHub repo (can be cloned)
+ * - generate: Has valid GitHub repo but will need AI generation
+ * - unknown: No GitHub repo found
+ *
+ * Note: Since we don't have a reference registry/index, "available" and "generate"
+ * are the same. We use "available" for consistency and reserve "generate" for
+ * future use when we can distinguish pre-existing vs needs-generation.
+ *
+ * @param resolvedDeps - Array of resolved dependencies with repo info
+ * @returns Array of reference matches with status
+ */
+declare function matchDependenciesToReferences(resolvedDeps: ResolvedDep[]): ReferenceMatch[];
+//#endregion
+//#region src/agents-md.d.ts
+/**
+ * AGENTS.md manipulation utilities
+ *
+ * Manages updating project AGENTS.md and agent-specific files with reference information.
+ */
+interface InstalledReference {
+  /** Dependency name */
+  dependency: string;
+  /** Reference identifier (matches reference file name without .md) */
+  reference: string;
+  /** Absolute path to reference file */
+  path: string;
+}
+/**
+ * Update or append Project References section in a markdown file.
+ * If the section exists, replaces its content. Otherwise, appends to end.
+ *
+ * @param filePath - Path to markdown file
+ * @param references - Array of installed references
+ */
+declare function appendReferencesSection(filePath: string, references: InstalledReference[]): void;
+/**
+ * Update AGENTS.md and agent-specific files with project references.
+ * Creates files if they don't exist.
+ *
+ * @param projectRoot - Project root directory
+ * @param references - Array of installed references to document
+ */
+declare function updateAgentFiles(projectRoot: string, references: InstalledReference[]): void;
+//#endregion
+//#region src/repo-manager.d.ts
+interface RepoStatusSummary {
+  total: number;
+  withReference: number;
+  missing: number;
+  diskBytes: number;
+}
+interface RepoStatusOptions {
+  onProgress?: (current: number, total: number, repo: string) => void;
+}
+interface UpdateAllOptions {
+  pattern?: string;
+  dryRun?: boolean;
+  /** Convert shallow clones to full clones */
+  unshallow?: boolean;
+  onProgress?: (repo: string, status: "updating" | "updated" | "skipped" | "error" | "unshallowed", message?: string) => void;
+}
+interface UpdateAllResult {
+  updated: string[];
+  skipped: string[];
+  unshallowed: string[];
+  errors: Array<{
+    repo: string;
+    error: string;
+  }>;
+}
+interface PruneOptions {
+  dryRun?: boolean;
+  onProgress?: (repo: string, reason: string) => void;
+}
+interface PruneResult {
+  removedFromIndex: string[];
+  orphanedDirs: string[];
+}
+interface GcOptions {
+  olderThanDays?: number;
+  withoutReference?: boolean;
+  dryRun?: boolean;
+  onProgress?: (repo: string, reason: string, sizeBytes?: number) => void;
+}
+interface GcResult {
+  removed: Array<{
+    repo: string;
+    reason: string;
+    sizeBytes: number;
+  }>;
+  freedBytes: number;
+}
+declare function getRepoStatus(options?: RepoStatusOptions): Promise<RepoStatusSummary>;
+declare function updateAllRepos(options?: UpdateAllOptions): Promise<UpdateAllResult>;
+declare function pruneRepos(options?: PruneOptions): Promise<PruneResult>;
+declare function gcRepos(options?: GcOptions): Promise<GcResult>;
+interface DiscoverOptions {
+  repoRoot?: string;
+  dryRun?: boolean;
+  onProgress?: (repo: string, provider: string) => void;
+}
+interface DiscoverResult {
+  discovered: Array<{
+    fullName: string;
+    qualifiedName: string;
+    localPath: string;
+  }>;
+  alreadyIndexed: number;
+}
+declare function discoverRepos(options?: DiscoverOptions): Promise<DiscoverResult>;
+//#endregion
+//#region src/models.d.ts
+/**
+ * Simplified provider info for CLI display
+ */
+interface ProviderInfo {
+  id: string;
+  name: string;
+  env: string[];
+}
+/**
+ * Simplified model info for CLI display
+ */
+interface ModelInfo {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  experimental?: boolean;
+  status?: "alpha" | "beta" | "deprecated";
+}
+/**
+ * Full provider with models for CLI display
+ */
+interface ProviderWithModels extends ProviderInfo {
+  models: ModelInfo[];
+}
+/**
+ * List all available providers from models.dev
+ */
+declare function listProviders(): Promise<ProviderInfo[]>;
+/**
+ * Get a specific provider with all its models
+ */
+declare function getProvider(providerId: string): Promise<ProviderWithModels | null>;
+/**
+ * Get all providers with their models
+ */
+declare function listProvidersWithModels(): Promise<ProviderWithModels[]>;
+/**
+ * Validate that a provider/model combination exists
+ */
+declare function validateProviderModel(providerId: string, modelId: string): Promise<{
+  valid: boolean;
+  error?: string;
+}>;
+//#endregion
+//#region src/installation.d.ts
+/**
+ * Installation utilities for upgrade/uninstall commands
+ */
+type InstallMethod = "curl" | "npm" | "pnpm" | "bun" | "brew" | "unknown";
+/**
+ * Detect how offworld was installed
+ */
+declare function detectInstallMethod(): InstallMethod;
+/**
+ * Get current installed version
+ */
+declare function getCurrentVersion(): string;
+/**
+ * Fetch latest version from appropriate source
+ */
+declare function fetchLatestVersion(method?: InstallMethod): Promise<string | null>;
+/**
+ * Execute upgrade for given method
+ */
+declare function executeUpgrade(method: InstallMethod, version: string): Promise<void>;
+/**
+ * Execute uninstall for given method
+ */
+declare function executeUninstall(method: InstallMethod): Promise<void>;
+/**
+ * Get shell config files to clean
+ */
+declare function getShellConfigFiles(): string[];
+/**
+ * Clean PATH entries from shell config
+ */
+declare function cleanShellConfig(filePath: string): boolean;
+//#endregion
+export { type AgentConfig, type AuthData, AuthError, type AuthStatus, AuthenticationError, type CanPushResult, type CheckResponse, CloneError, type CloneOptions, CommitExistsError, CommitNotFoundError, type Config, ConflictError, DEFAULT_IGNORE_PATTERNS, type Dependency, type DiscoverOptions, type DiscoverResult, type FileIndex, type FileIndexEntry, type FileRole, type GcOptions, type GcResult, type GenerateReferenceOptions, type GenerateReferenceResult, type GetMapEntryOptions, GitError, GitHubError, type GitHubRepoMetadata, type GlobalMap, type GlobalMapRepoEntry, type InstallMethod, type InstallReferenceMeta, type InstalledReference, InvalidInputError, InvalidReferenceError, KNOWN_MAPPINGS, LowStarsError, type ManifestType, type MapEntry, type ModelInfo, NetworkError, NotGitRepoError, NotLoggedInError, OpenCodeSDKError, PathNotFoundError, Paths, PrivateRepoError, type ProjectMap, type ProjectMapRepoEntry, type ProviderInfo, type ProviderWithModels, type PruneOptions, type PruneResult, type PullResponse, PushNotAllowedError, type PushResponse, RateLimitError, type ReferenceData, type ReferenceMatch, type ReferenceStatus, type RemoveOptions, RepoExistsError, RepoNotFoundError, type RepoSource, RepoSourceError, type RepoStatusOptions, type RepoStatusSummary, type ResolvedDep, type SearchMapOptions, type SearchResult, type StalenessResult, type StreamPromptOptions, type StreamPromptResult, SyncError, RepoNotFoundError$1 as SyncRepoNotFoundError, TokenExpiredError, type UpdateAllOptions, type UpdateAllResult, type UpdateOptions, type UpdateResult, VERSION, agents, appendReferencesSection, canPushToWeb, checkRemote, checkRemoteByName, checkStaleness, cleanShellConfig, clearAuthData, cloneRepo, detectInstallMethod, detectInstalledAgents, detectManifestType, discoverRepos, executeUninstall, executeUpgrade, expandTilde, fetchGitHubMetadata, fetchLatestVersion, fetchRepoStars, gcRepos, generateReferenceWithAI, getAgentConfig, getAllAgentConfigs, getAuthPath, getAuthStatus, getClonedRepoPath, getCommitDistance, getCommitSha, getConfigPath, getCurrentVersion, getMapEntry, getMetaPath, getMetaRoot, getProjectMapPath, getProvider, getReferenceFileNameForSource, getReferencePath, getRepoPath, getRepoRoot, getRepoStatus, getShellConfigFiles, getToken, getTokenOrNull, installGlobalSkill, installReference, isLoggedIn, isReferenceInstalled, isRepoCloned, isShallowClone, listProviders, listProvidersWithModels, listRepos, loadAuthData, loadConfig, matchDependenciesToReferences, parseDependencies, parseRepoInput, pruneRepos, pullReference, pullReferenceByName, pushReference, readGlobalMap, refreshAccessToken, removeGlobalMapEntry, removeRepo, resolveDependencyRepo, resolveFromNpm, resolveRepoKey, saveAuthData, saveConfig, searchMap, streamPrompt, toMetaDirName, toReferenceFileName, toReferenceName, unshallowRepo, updateAgentFiles, updateAllRepos, updateRepo, upsertGlobalMapEntry, validateProviderModel, validatePushAllowed, writeGlobalMap, writeProjectMap };
+//# sourceMappingURL=index.d.mts.map