@larkiny/astro-github-loader 0.11.2 → 0.12.0

package/README.md

@@ -9,7 +9,7 @@ Load content from GitHub repositories into Astro content collections with flexib
 - 🛠️ **Content Transforms** - Apply custom transformations to content during import, with pattern-specific transforms
 - ⚡ **Intelligent Change Detection** - Ref-aware commit tracking that only triggers re-imports when your target branch/tag actually changes
 - 🔒 **Stable Imports** - Non-destructive approach that preserves local content collections
-- 🚀 **Optimized Performance** - Smart directory scanning to minimize GitHub API calls
+- 🚀 **Optimized Performance** - Git Trees API for efficient file discovery with minimal API calls
 
 ## Quick Start
 
@@ -68,10 +68,10 @@ export const collections = {
 
 The loader supports two authentication methods with different rate limits:
 
-| Method | Rate Limit | Best For |
-|--------|-----------|----------|
+| Method                       | Rate Limit           | Best For                                      |
+| ---------------------------- | -------------------- | --------------------------------------------- |
 | **GitHub App** (Recommended) | 15,000 requests/hour | Production, large imports, organizational use |
-| **Personal Access Token** | 5,000 requests/hour | Development, small imports |
+| **Personal Access Token**    | 5,000 requests/hour  | Development, small imports                    |
 
 ### Option 1: GitHub App Authentication (Recommended - 3x Rate Limit)
 
@@ -252,6 +252,7 @@ export const collections = {
 ```
 
 In this example:
+
 - **Stable docs** (v2.0.0 tag): Never re-imports, provides stable reference
 - **Latest docs** (main branch): Only re-imports when main branch changes
 - **Beta features** (beta branch): Only re-imports when beta branch changes
@@ -500,7 +501,6 @@ const REMOTE_CONTENT: ImportOptions[] = [
             return `/reference/algokit-cli`;
           },
           global: true,
-          description: "Map CLI reference links to reference section",
         },
 
         // Transform README links to introduction
@@ -510,7 +510,6 @@ const REMOTE_CONTENT: ImportOptions[] = [
             return `/introduction`;
           },
           global: true,
-          description: "Map README links to introduction page",
         },
       ],
     },
@@ -518,39 +517,6 @@ const REMOTE_CONTENT: ImportOptions[] = [
 ];
 ```
 
-## Link Transformation Utilities
-
-Handle markdown links with anchor fragments using built-in utilities:
-
-```typescript
-import {
-  createLinkTransform,
-  extractAnchor,
-  removeMarkdownExtension,
-} from "@larkiny/astro-github-loader";
-
-const linkTransform = createLinkTransform({
-  baseUrl: "/docs/imported",
-  pathTransform: (path, context) => {
-    const { path: cleanPath, anchor } = extractAnchor(path);
-
-    // Custom link handling logic
-    if (cleanPath === "README.md") {
-      return `/docs/imported/overview${anchor}`;
-    }
-
-    // Use utility to remove .md extension and preserve anchors
-    return `/docs/imported/${removeMarkdownExtension(path)}`;
-  },
-});
-```
-
-### Link Transform Utilities
-
-- **`extractAnchor(path)`** - Returns `{path, anchor}` separating the anchor fragment
-- **`removeMarkdownExtension(path)`** - Removes `.md`/`.mdx` extensions while preserving anchors
-- **`createLinkTransform(options)`** - Main transform with custom path handling
-
 ## Asset Import and Management
 
 Automatically detect, download, and transform asset references:
@@ -584,17 +550,53 @@ const REMOTE_CONTENT_WITH_ASSETS: ImportOptions[] = [
 
 ## File Management Strategy
 
-> **⚠️ Important: Do not use `clear: true`**
->
-> The `clear: true` option should not be used with the current implementation due to how Astro content collection syncing works. Mass file deletions can cause Astro to invalidate entire content collections, leading to 404 errors and build instability.
->
-> **Instead**: If you need to handle file deletions, renames, or path restructuring from the source repository:
->
-> 1. Manually delete the local import folders (e.g., `src/content/docs/imported`)
-> 2. Re-run the import process
-> 3. Fresh content will be imported with the new structure
->
-> This approach ensures your site remains stable while handling structural changes.
+The `clear` option enables selective replacement of content collection entries during import. When enabled, existing entries are atomically replaced (deleted then re-added) one at a time, preserving content collection stability.
+
+### Using the Clear Option
+
+```typescript
+// Per-config clear (recommended)
+const REMOTE_CONTENT: ImportOptions[] = [
+  {
+    name: "Docs that need clearing",
+    owner: "your-org",
+    repo: "docs-repo",
+    clear: true, // Enable clearing for this config only
+    includes: [
+      { pattern: "docs/**/*.md", basePath: "src/content/docs/imported" },
+    ],
+  },
+  {
+    name: "Docs that don't need clearing",
+    owner: "your-org",
+    repo: "other-docs",
+    clear: false, // Explicitly disable (or omit for default behavior)
+    includes: [
+      { pattern: "guides/**/*.md", basePath: "src/content/docs/guides" },
+    ],
+  },
+];
+
+// Or use global clear with per-config override
+await githubLoader({
+  octokit,
+  configs: REMOTE_CONTENT,
+  clear: true, // Global default - can be overridden per-config
+}).load(context);
+```
+
+### When to Use Clear
+
+- **Use `clear: true`** when you need to ensure stale entries are removed (e.g., files renamed or deleted in the source repo)
+- **Use `clear: false`** (default) for incremental updates where you want to preserve existing entries
+
+### How It Works
+
+Unlike a bulk clear operation, the loader uses a selective delete-before-set approach:
+
+1. For each file being imported, if an entry already exists, it's deleted immediately before the new entry is added
+2. This atomic replacement ensures the content collection is never empty
+3. Astro's content collection system handles individual deletions gracefully
 
 ## Change Detection & Dry-Run Mode
 
@@ -647,6 +649,7 @@ The loader uses intelligent, ref-aware change detection:
 - **Efficient checking**: Only the latest commit of your target ref is checked
 
 **Examples**:
+
 - Config tracking `main` branch → only `main` commits trigger re-import
 - Config tracking `v2.1.0` tag → never re-imports (tags are immutable)
 - Config tracking `feature-branch` → ignores commits to `main`, `develop`, etc.
@@ -708,13 +711,16 @@ interface LinkMapping {
   /** Replacement string or function */
   replacement:
     | string
-    | ((match: string, anchor: string, context: any) => string);
+    | ((match: string, anchor: string, context: LinkTransformContext) => string);
 
   /** Apply to all links, not just unresolved internal links (default: false) */
   global?: boolean;
 
-  /** Description for debugging (optional) */
-  description?: string;
+  /** Function to determine if this mapping should apply to the current file context */
+  contextFilter?: (context: LinkTransformContext) => boolean;
+
+  /** Automatically handle relative links by prefixing with target base path (default: false) */
+  relativeLinks?: boolean;
 }
 
 interface IncludePattern {
@@ -730,15 +736,17 @@ interface IncludePattern {
   /**
    * Map of source paths to target paths for controlling where files are imported.
    *
-   * Supports two types of mappings:
-   * - **File mapping**: `'docs/README.md': 'docs/overview.md'` - moves a specific file to a new path
-   * - **Folder mapping**: `'docs/capabilities/': 'docs/'` - moves all files from source folder to target folder
+   * Supports two mapping formats:
+   * - **Simple string**: `'docs/README.md': 'docs/overview.md'`
+   * - **Enhanced object**: `'docs/api/': { target: 'api/', crossSectionPath: '/reference/api' }`
+   *
+   * And two mapping scopes:
+   * - **File mapping**: Exact file path match (e.g., `'docs/README.md': 'docs/overview.md'`)
+   * - **Folder mapping**: Trailing slash moves all files (e.g., `'docs/capabilities/': 'docs/'`)
    *
    * **Important**: Folder mappings require trailing slashes to distinguish from file mappings.
-   * - ✅ `'docs/capabilities/': 'docs/'` (folder mapping - moves all files)
-   * - ❌ `'docs/capabilities': 'docs/'` (treated as exact file match)
    */
-  pathMappings?: Record<string, string>;
+  pathMappings?: Record<string, PathMappingValue>;
 }
 ```
 
@@ -766,8 +774,8 @@ type TransformFunction = (content: string, context: TransformContext) => string;
 
 The loader includes several optimizations:
 
-- **Smart directory scanning**: Only scans directories that match include patterns
-- **Efficient API usage**: Minimizes GitHub API calls through targeted requests
+- **Git Trees API**: Retrieves the entire repository file tree in a single API call (2 total: 1 for commit SHA + 1 for tree), replacing recursive directory traversal
+- **Efficient API usage**: Minimizes GitHub API calls regardless of repository size or depth
 - **Ref-aware change detection**: Tracks commit SHA for specific git references (branches/tags) to avoid unnecessary downloads when unrelated branches change
 - **Concurrent processing**: Downloads and processes files in parallel
 

package/dist/github.assets.d.ts

@@ -0,0 +1,70 @@
+import { Octokit } from "octokit";
+import type { Logger } from "./github.logger.js";
+import type { ImportOptions } from "./github.types.js";
+/**
+ * Resolves the effective asset configuration for an import.
+ *
+ * If `assetsPath` and `assetsBaseUrl` are explicitly provided, uses them (existing behavior).
+ * If omitted, derives co-located defaults from the matched include pattern's basePath:
+ * - assetsPath: `{basePath}/assets/` (physical directory on disk)
+ * - assetsBaseUrl: `./assets` (relative reference in markdown)
+ *
+ * @param options - Import options that may or may not have explicit asset config
+ * @param filePath - The file being processed (used to find the matched include pattern)
+ * @returns Resolved assetsPath and assetsBaseUrl, or null if assets should not be processed
+ * @internal
+ */
+export declare function resolveAssetConfig(options: ImportOptions, filePath: string): {
+    assetsPath: string;
+    assetsBaseUrl: string;
+} | null;
+/**
+ * Detects asset references in markdown content using regex patterns
+ * @param content - The markdown content to parse
+ * @param assetPatterns - File extensions to treat as assets
+ * @returns Array of detected asset paths
+ * @internal
+ */
+export declare function detectAssets(content: string, assetPatterns?: string[]): string[];
+/**
+ * Downloads an asset from GitHub and saves it locally
+ * @param octokit - GitHub API client
+ * @param owner - Repository owner
+ * @param repo - Repository name
+ * @param ref - Git reference
+ * @param assetPath - Path to the asset in the repository
+ * @param localPath - Local path where the asset should be saved
+ * @param signal - Abort signal for cancellation
+ * @returns Promise that resolves when the asset is downloaded
+ * @internal
+ */
+export declare function downloadAsset(octokit: Octokit, owner: string, repo: string, ref: string, assetPath: string, localPath: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Transforms asset references in markdown content to use local paths
+ * @param content - The markdown content to transform
+ * @param assetMap - Map of original asset paths to new local paths
+ * @returns Transformed content with updated asset references
+ * @internal
+ */
+export declare function transformAssetReferences(content: string, assetMap: Map<string, string>): string;
+/**
+ * Resolves an asset path relative to a base path
+ * @internal
+ */
+export declare function resolveAssetPath(basePath: string, assetPath: string): string;
+/**
+ * Processes assets in markdown content by detecting, downloading, and transforming references
+ * @param content - The markdown content to process
+ * @param filePath - The file path of the markdown file being processed
+ * @param options - Configuration options including asset settings
+ * @param octokit - GitHub API client
+ * @param logger - Logger instance for output
+ * @param signal - Abort signal for cancellation
+ * @returns Promise that resolves to transformed content
+ * @internal
+ */
+export declare function processAssets(content: string, filePath: string, options: ImportOptions, octokit: Octokit, logger: Logger, signal?: AbortSignal): Promise<{
+    content: string;
+    assetsDownloaded: number;
+    assetsCached: number;
+}>;

package/dist/github.assets.js

@@ -0,0 +1,253 @@
+import { existsSync, promises as fs } from "node:fs";
+import { join, dirname, basename, extname } from "node:path";
+import { shouldIncludeFile } from "./github.paths.js";
+/**
+ * Default asset patterns for common image and media file types
+ * @internal
+ */
+const DEFAULT_ASSET_PATTERNS = [
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".svg",
+    ".webp",
+    ".ico",
+    ".bmp",
+];
+/**
+ * Resolves the effective asset configuration for an import.
+ *
+ * If `assetsPath` and `assetsBaseUrl` are explicitly provided, uses them (existing behavior).
+ * If omitted, derives co-located defaults from the matched include pattern's basePath:
+ * - assetsPath: `{basePath}/assets/` (physical directory on disk)
+ * - assetsBaseUrl: `./assets` (relative reference in markdown)
+ *
+ * @param options - Import options that may or may not have explicit asset config
+ * @param filePath - The file being processed (used to find the matched include pattern)
+ * @returns Resolved assetsPath and assetsBaseUrl, or null if assets should not be processed
+ * @internal
+ */
+export function resolveAssetConfig(options, filePath) {
+    // Explicit config takes precedence
+    if (options.assetsPath && options.assetsBaseUrl) {
+        return {
+            assetsPath: options.assetsPath,
+            assetsBaseUrl: options.assetsBaseUrl,
+        };
+    }
+    // If only one is set, that's a misconfiguration — skip
+    if (options.assetsPath || options.assetsBaseUrl) {
+        return null;
+    }
+    // Derive co-located defaults from the matched include pattern's basePath
+    const includeResult = shouldIncludeFile(filePath, options);
+    if (includeResult.included && includeResult.matchedPattern) {
+        const basePath = includeResult.matchedPattern.basePath;
+        return {
+            assetsPath: join(basePath, "assets"),
+            assetsBaseUrl: "./assets",
+        };
+    }
+    return null;
+}
+/**
+ * Detects asset references in markdown content using regex patterns
+ * @param content - The markdown content to parse
+ * @param assetPatterns - File extensions to treat as assets
+ * @returns Array of detected asset paths
+ * @internal
+ */
+export function detectAssets(content, assetPatterns = DEFAULT_ASSET_PATTERNS) {
+    const assets = [];
+    const patterns = assetPatterns.map((ext) => ext.toLowerCase());
+    // Match markdown images: ![alt](path)
+    const imageRegex = /!\[[^\]]*\]\(([^)]+)\)/g;
+    let match;
+    while ((match = imageRegex.exec(content)) !== null) {
+        const assetPath = match[1];
+        // Only include relative paths and assets matching our patterns
+        if (assetPath.startsWith("./") ||
+            assetPath.startsWith("../") ||
+            !assetPath.includes("://")) {
+            const ext = extname(assetPath).toLowerCase();
+            if (patterns.includes(ext)) {
+                assets.push(assetPath);
+            }
+        }
+    }
+    // Match HTML img tags: <img src="path">
+    const htmlImgRegex = /<img[^>]+src\s*=\s*["']([^"']+)["'][^>]*>/gi;
+    while ((match = htmlImgRegex.exec(content)) !== null) {
+        const assetPath = match[1];
+        if (assetPath.startsWith("./") ||
+            assetPath.startsWith("../") ||
+            !assetPath.includes("://")) {
+            const ext = extname(assetPath).toLowerCase();
+            if (patterns.includes(ext)) {
+                assets.push(assetPath);
+            }
+        }
+    }
+    return [...new Set(assets)]; // Remove duplicates
+}
+/**
+ * Downloads an asset from GitHub and saves it locally
+ * @param octokit - GitHub API client
+ * @param owner - Repository owner
+ * @param repo - Repository name
+ * @param ref - Git reference
+ * @param assetPath - Path to the asset in the repository
+ * @param localPath - Local path where the asset should be saved
+ * @param signal - Abort signal for cancellation
+ * @returns Promise that resolves when the asset is downloaded
+ * @internal
+ */
+export async function downloadAsset(octokit, owner, repo, ref, assetPath, localPath, signal) {
+    try {
+        const { data } = await octokit.rest.repos.getContent({
+            owner,
+            repo,
+            path: assetPath,
+            ref,
+            request: { signal },
+        });
+        if (Array.isArray(data)) {
+            throw new Error(`Asset ${assetPath} is a directory, not a file`);
+        }
+        if (data.type !== "file" || !data.download_url) {
+            throw new Error(`Asset ${assetPath} is not a valid file (type: ${data.type}, downloadUrl: ${data.download_url})`);
+        }
+        const response = await fetch(data.download_url, { signal });
+        if (!response.ok) {
+            throw new Error(`Failed to download asset: ${response.status} ${response.statusText}`);
+        }
+        const buffer = await response.arrayBuffer();
+        const dir = dirname(localPath);
+        if (!existsSync(dir)) {
+            await fs.mkdir(dir, { recursive: true });
+        }
+        await fs.writeFile(localPath, new Uint8Array(buffer));
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "status" in error &&
+            error.status === 404) {
+            throw new Error(`Asset not found: ${assetPath}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Transforms asset references in markdown content to use local paths
+ * @param content - The markdown content to transform
+ * @param assetMap - Map of original asset paths to new local paths
+ * @returns Transformed content with updated asset references
+ * @internal
+ */
+export function transformAssetReferences(content, assetMap) {
+    let transformedContent = content;
+    for (const [originalPath, newPath] of assetMap) {
+        // Transform markdown images
+        const imageRegex = new RegExp(`(!)\\[([^\\]]*)\\]\\(\\s*${escapeRegExp(originalPath)}\\s*\\)`, "g");
+        transformedContent = transformedContent.replace(imageRegex, `$1[$2](${newPath})`);
+        // Transform HTML img tags
+        const htmlRegex = new RegExp(`(<img[^>]+src\\s*=\\s*["'])${escapeRegExp(originalPath)}(["'][^>]*>)`, "gi");
+        transformedContent = transformedContent.replace(htmlRegex, `$1${newPath}$2`);
+    }
+    return transformedContent;
+}
+/**
+ * Escapes special regex characters in a string
+ * @internal
+ */
+function escapeRegExp(string) {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Resolves an asset path relative to a base path
+ * @internal
+ */
+export function resolveAssetPath(basePath, assetPath) {
+    if (assetPath.startsWith("./")) {
+        return join(dirname(basePath), assetPath.slice(2));
+    }
+    else if (assetPath.startsWith("../")) {
+        return join(dirname(basePath), assetPath);
+    }
+    return assetPath;
+}
+/**
+ * Processes assets in markdown content by detecting, downloading, and transforming references
+ * @param content - The markdown content to process
+ * @param filePath - The file path of the markdown file being processed
+ * @param options - Configuration options including asset settings
+ * @param octokit - GitHub API client
+ * @param logger - Logger instance for output
+ * @param signal - Abort signal for cancellation
+ * @returns Promise that resolves to transformed content
+ * @internal
+ */
+export async function processAssets(content, filePath, options, octokit, logger, signal) {
+    const { owner, repo, ref = "main", assetsPath, assetsBaseUrl, assetPatterns, } = options;
+    logger.verbose(`🖼️  Processing assets for ${filePath}`);
+    logger.debug(`    assetsPath: ${assetsPath}`);
+    logger.debug(`    assetsBaseUrl: ${assetsBaseUrl}`);
+    if (!assetsPath || !assetsBaseUrl) {
+        logger.verbose(`    ⏭️  Skipping asset processing - missing assetsPath or assetsBaseUrl`);
+        return { content, assetsDownloaded: 0, assetsCached: 0 };
+    }
+    // Detect assets in the content
+    const detectedAssets = detectAssets(content, assetPatterns);
+    logger.verbose(`    📸 Detected ${detectedAssets.length} assets`);
+    if (detectedAssets.length > 0) {
+        logger.debug(`    Assets: ${detectedAssets.join(", ")}`);
+    }
+    if (detectedAssets.length === 0) {
+        return { content, assetsDownloaded: 0, assetsCached: 0 };
+    }
+    const assetMap = new Map();
+    let assetsDownloaded = 0;
+    let assetsCached = 0;
+    // Process each detected asset
+    await Promise.all(detectedAssets.map(async (assetPath) => {
+        logger.logAssetProcessing("Processing", assetPath);
+        try {
+            // Resolve the asset path relative to the current markdown file
+            const resolvedAssetPath = resolveAssetPath(filePath, assetPath);
+            logger.debug(`    🔗 Resolved path: ${resolvedAssetPath}`);
+            // Generate unique filename to avoid conflicts
+            const originalFilename = basename(assetPath);
+            const ext = extname(originalFilename);
+            const nameWithoutExt = basename(originalFilename, ext);
+            const uniqueFilename = `${nameWithoutExt}-${Date.now()}${ext}`;
+            const localPath = join(assetsPath, uniqueFilename);
+            logger.debug(`    💾 Local path: ${localPath}`);
+            // Check if asset already exists (simple cache check)
+            if (existsSync(localPath)) {
+                logger.logAssetProcessing("Cached", assetPath);
+                assetsCached++;
+            }
+            else {
+                // Download the asset
+                logger.logAssetProcessing("Downloading", assetPath, `from ${owner}/${repo}@${ref}:${resolvedAssetPath}`);
+                await downloadAsset(octokit, owner, repo, ref, resolvedAssetPath, localPath, signal);
+                logger.logAssetProcessing("Downloaded", assetPath);
+                assetsDownloaded++;
+            }
+            // Generate URL for the transformed reference
+            const assetUrl = `${assetsBaseUrl}/${uniqueFilename}`.replace(/\/+/g, "/");
+            logger.debug(`    🔄 Transform: ${assetPath} -> ${assetUrl}`);
+            // Map the transformation
+            assetMap.set(assetPath, assetUrl);
+        }
+        catch (error) {
+            logger.warn(`    ❌ Failed to process asset ${assetPath}: ${error}`);
+        }
+    }));
+    logger.verbose(`    🗺️  Processed ${assetMap.size} assets: ${assetsDownloaded} downloaded, ${assetsCached} cached`);
+    // Transform the content with new asset references
+    const transformedContent = transformAssetReferences(content, assetMap);
+    return { content: transformedContent, assetsDownloaded, assetsCached };
+}

package/dist/github.auth.js

@@ -4,7 +4,7 @@ import { createAppAuth } from "@octokit/auth-app";
  * Type guard to check if config is GitHub App authentication
  */
 function isGitHubAppAuth(config) {
-    return 'appId' in config && 'privateKey' in config && 'installationId' in config;
+    return ("appId" in config && "privateKey" in config && "installationId" in config);
 }
 /**
  * Creates an authenticated Octokit instance with support for both Personal Access Tokens
@@ -91,15 +91,17 @@ export function createOctokitFromEnv() {
     if (appId && privateKey && installationId) {
         // Decode private key if it's base64 encoded (for easier .env storage)
         let decodedPrivateKey = privateKey;
-        if (!privateKey.includes('BEGIN RSA PRIVATE KEY') && !privateKey.includes('BEGIN PRIVATE KEY')) {
+        if (!privateKey.includes("BEGIN RSA PRIVATE KEY") &&
+            !privateKey.includes("BEGIN PRIVATE KEY")) {
             try {
-                decodedPrivateKey = Buffer.from(privateKey, 'base64').toString('utf-8');
+                decodedPrivateKey = Buffer.from(privateKey, "base64").toString("utf-8");
             }
             catch {
                 // If decoding fails, use as-is (might already be plaintext)
             }
         }
-        console.log('✓ Using GitHub App authentication (15,000 requests/hour)');
+        // eslint-disable-next-line no-console -- startup message before logger exists
+        console.log("✓ Using GitHub App authentication (15,000 requests/hour)");
         return createAuthenticatedOctokit({
             appId,
             privateKey: decodedPrivateKey,
@@ -109,11 +111,13 @@ export function createOctokitFromEnv() {
     // Fallback to Personal Access Token
     const token = process.env.GITHUB_TOKEN;
     if (token) {
-        console.log('✓ Using Personal Access Token authentication (5,000 requests/hour)');
-        console.log('💡 Consider switching to GitHub App for 3x higher rate limits');
+        // eslint-disable-next-line no-console -- startup message before logger exists
+        console.log("✓ Using Personal Access Token authentication (5,000 requests/hour)");
+        // eslint-disable-next-line no-console -- startup message before logger exists
+        console.log("💡 Consider switching to GitHub App for 3x higher rate limits");
         return createAuthenticatedOctokit({ token });
     }
-    throw new Error('No GitHub authentication credentials found. Please set either:\n' +
-        '  - GITHUB_TOKEN (for PAT authentication)\n' +
-        '  - GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_INSTALLATION_ID (for GitHub App authentication)');
+    throw new Error("No GitHub authentication credentials found. Please set either:\n" +
+        "  - GITHUB_TOKEN (for PAT authentication)\n" +
+        "  - GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_INSTALLATION_ID (for GitHub App authentication)");
 }

package/dist/github.cleanup.d.ts

@@ -1,5 +1,6 @@
-import type { ImportOptions, LoaderContext, SyncStats } from "./github.types.js";
+import { Octokit } from "octokit";
+import type { ExtendedLoaderContext, ImportOptions, SyncStats } from "./github.types.js";
 /**
  * Performs selective cleanup of obsolete files
  */
-export declare function performSelectiveCleanup(config: ImportOptions, context: LoaderContext, octokit: any, signal?: AbortSignal): Promise<SyncStats>;
+export declare function performSelectiveCleanup(config: ImportOptions, context: ExtendedLoaderContext, octokit: Octokit, signal?: AbortSignal): Promise<SyncStats>;