@aspruyt/xfg 4.0.2 → 4.0.4

package/dist/shared/command-executor.js

@@ -1,26 +1,31 @@
 import { execSync } from "node:child_process";
 import { sanitizeCredentials } from "./sanitize-utils.js";
 export class ShellCommandExecutor {
+    baseEnv;
+    constructor(baseEnv) {
+        this.baseEnv = baseEnv;
+    }
     async exec(command, cwd, options) {
         try {
             return execSync(command, {
                 cwd,
                 encoding: "utf-8",
                 stdio: ["pipe", "pipe", "pipe"],
-                env: options?.env ? { ...process.env, ...options.env } : undefined,
+                env: options?.env
+                    ? { ...this.baseEnv, ...options.env }
+                    : this.baseEnv,
             }).trim();
         }
         catch (error) {
-            // Ensure stderr is always a string for consistent error handling
+            // Normalise and sanitise the exec error so downstream retry logic
+            // sees a string stderr with no raw credentials.
             const execError = error;
             if (execError.stderr && typeof execError.stderr !== "string") {
                 execError.stderr = execError.stderr.toString();
             }
-            // Sanitize credentials from stderr before including in error
             if (execError.stderr) {
                 execError.stderr = sanitizeCredentials(execError.stderr);
             }
-            // Include sanitized stderr in error message for better debugging
             if (execError.stderr && execError.message) {
                 execError.message =
                     sanitizeCredentials(execError.message) + "\n" + execError.stderr;
@@ -32,7 +37,6 @@ export class ShellCommandExecutor {
         }
     }
 }
-export const defaultExecutor = new ShellCommandExecutor();
 /** Extract stderr string from an exec error (child_process errors attach stderr). */
 export function getStderr(error) {
     if (error != null && typeof error === "object" && "stderr" in error) {

package/dist/shared/env.d.ts

@@ -9,6 +9,10 @@ export interface EnvInterpolationOptions {
      * and has no default value. If false, leaves the placeholder as-is.
      */
     strict: boolean;
+    /**
+     * Environment variables to resolve from.
+     */
+    env: Record<string, string | undefined>;
 }
 /**
  * Interpolate environment variables in a JSON object.
@@ -18,14 +22,10 @@ export interface EnvInterpolationOptions {
  * - ${VAR:-default} - Replace with env value, or use default if missing
  * - ${VAR:?message} - Replace with env value, or throw error with message if missing
  * - $${VAR} - Escape: outputs literal ${VAR} without interpolation
- *
- * @param json - The JSON object to process
- * @param options - Interpolation options (default: strict mode)
- * @returns A new object with interpolated values
  */
-export declare function interpolateEnvVars(json: Record<string, unknown>, options?: EnvInterpolationOptions): Record<string, unknown>;
+export declare function interpolateEnvVars(json: Record<string, unknown>, options: EnvInterpolationOptions): Record<string, unknown>;
 /**
  * Interpolate environment variables in content of any supported type.
  * Handles objects, strings, and string arrays.
  */
-export declare function interpolateContent(content: Record<string, unknown> | string | string[], options?: EnvInterpolationOptions): Record<string, unknown> | string | string[];
+export declare function interpolateContent(content: Record<string, unknown> | string | string[], options: EnvInterpolationOptions): Record<string, unknown> | string | string[];

package/dist/shared/env.js

@@ -4,9 +4,7 @@
  * Use $${VAR} to escape and output literal ${VAR}.
  */
 import { interpolateString, interpolateValue, } from "./interpolation-engine.js";
-const DEFAULT_OPTIONS = {
-    strict: true,
-};
+import { ValidationError } from "./errors.js";
 /**
  * Regex to match environment variable placeholders.
  * Captures:
@@ -29,26 +27,25 @@ const ENV_VAR_REGEX = /\$\{([A-Za-z_][A-Za-z0-9_.]*)(?::([?-])([^}]*))?\}/g;
  */
 const ESCAPED_VAR_REGEX = /\$\$\{((?!xfg:)[^}]+)\}/g;
 function buildEnvConfig(options) {
+    const envSource = options.env;
     function resolveEnvVar(match, varName, modifier, defaultOrMsg) {
-        const envValue = process.env[varName];
-        // Variable exists - use its value
+        // Resolution follows bash parameter expansion semantics:
+        // ${VAR} → value or error, ${VAR:-fallback} → value or fallback,
+        // ${VAR:?msg} → value or throw with msg.
+        const envValue = envSource[varName];
         if (envValue !== undefined) {
             return envValue;
         }
-        // Has default value (:-default)
         if (modifier === "-") {
             return defaultOrMsg ?? "";
         }
-        // Required with message (:?message)
         if (modifier === "?") {
             const message = defaultOrMsg || `is required`;
-            throw new Error(`${varName}: ${message}`);
+            throw new ValidationError(`${varName}: ${message}`);
         }
-        // No modifier - check strictness
         if (options.strict) {
-            throw new Error(`Missing required environment variable: ${varName}`);
+            throw new ValidationError(`Missing required environment variable: ${varName}`);
         }
-        // Non-strict mode - leave placeholder as-is
         return match;
     }
     return {
@@ -66,19 +63,15 @@ function buildEnvConfig(options) {
  * - ${VAR:-default} - Replace with env value, or use default if missing
  * - ${VAR:?message} - Replace with env value, or throw error with message if missing
  * - $${VAR} - Escape: outputs literal ${VAR} without interpolation
- *
- * @param json - The JSON object to process
- * @param options - Interpolation options (default: strict mode)
- * @returns A new object with interpolated values
  */
-export function interpolateEnvVars(json, options = DEFAULT_OPTIONS) {
+export function interpolateEnvVars(json, options) {
     return interpolateValue(json, buildEnvConfig(options));
 }
 /**
  * Interpolate environment variables in content of any supported type.
  * Handles objects, strings, and string arrays.
  */
-export function interpolateContent(content, options = DEFAULT_OPTIONS) {
+export function interpolateContent(content, options) {
     const config = buildEnvConfig(options);
     if (typeof content === "string") {
         return interpolateString(content, config);

package/dist/shared/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Thrown when config validation fails.
+ * Distinguishable from I/O errors by type, so callers and retry logic
+ * can treat validation failures as permanent without message-parsing.
+ */
+export declare class ValidationError extends Error {
+    readonly name = "ValidationError";
+    constructor(message: string);
+}
+/**
+ * Thrown when a GitHub GraphQL API call fails.
+ * Standardizes all GraphQL error messages under one type so catch blocks
+ * and retry logic can identify them without message-parsing.
+ */
+export declare class GraphQLApiError extends Error {
+    readonly name = "GraphQLApiError";
+    constructor(message: string);
+}
+export declare class SyncError extends Error {
+    readonly name = "SyncError";
+    constructor(message: string);
+}
+export declare class LifecycleError extends Error {
+    readonly name = "LifecycleError";
+    constructor(message: string);
+}

package/dist/shared/errors.js

@@ -0,0 +1,34 @@
+/**
+ * Thrown when config validation fails.
+ * Distinguishable from I/O errors by type, so callers and retry logic
+ * can treat validation failures as permanent without message-parsing.
+ */
+export class ValidationError extends Error {
+    name = "ValidationError";
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * Thrown when a GitHub GraphQL API call fails.
+ * Standardizes all GraphQL error messages under one type so catch blocks
+ * and retry logic can identify them without message-parsing.
+ */
+export class GraphQLApiError extends Error {
+    name = "GraphQLApiError";
+    constructor(message) {
+        super(message);
+    }
+}
+export class SyncError extends Error {
+    name = "SyncError";
+    constructor(message) {
+        super(message);
+    }
+}
+export class LifecycleError extends Error {
+    name = "LifecycleError";
+    constructor(message) {
+        super(message);
+    }
+}

package/dist/shared/gh-api-utils.d.ts

@@ -1,11 +1,19 @@
-import type { ICommandExecutor } from "../shared/command-executor.js";
-import type { GitHubRepoInfo } from "../shared/repo-detector.js";
-import type { GitHubAppTokenManager } from "../vcs/github-app-token-manager.js";
+import type { ICommandExecutor } from "./command-executor.js";
+import type { GitHubRepoInfo } from "./repo-detector.js";
+import type { DebugLog } from "./logger.js";
+interface ITokenManager {
+    getTokenForRepo(repoInfo: GitHubRepoInfo): Promise<string | null>;
+}
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 export interface GhApiOptions {
     token?: string;
     host?: string;
 }
+interface GhApiCallParams {
+    payload?: unknown;
+    options?: GhApiOptions;
+    paginate?: boolean;
+}
 /**
  * Get the hostname flag for gh commands.
  * Returns "--hostname HOST" for GHE, empty string for github.com.
@@ -19,28 +27,27 @@ export declare function buildTokenEnv(token?: string): Record<string, string> |
 export declare class GhApiClient {
     private readonly executor;
     private readonly retries;
-    constructor(executor: ICommandExecutor, retries: number);
-    call(method: HttpMethod, endpoint: string, payload?: unknown, options?: GhApiOptions, paginate?: boolean): Promise<string>;
+    private readonly cwd;
+    constructor(executor: ICommandExecutor, retries: number, cwd: string);
+    call(method: HttpMethod, endpoint: string, params?: GhApiCallParams): Promise<string>;
 }
 /**
- * Resolve a GitHub token for a repo: GitHub App token → GH_TOKEN env fallback.
+ * Resolve a GitHub token for a repo: GitHub App token → envToken fallback.
  * Returns { token, skipped } where skipped=true means no App installation found
- * and no GH_TOKEN is available. Both sync and settings paths use this function.
+ * for this owner (token will be undefined). Both sync and settings paths use this.
  */
-export declare function resolveGitHubToken(repoInfo: GitHubRepoInfo, tokenManager: GitHubAppTokenManager | null, context: string, log?: {
-    debug(msg: string): void;
-}, envToken?: string): Promise<{
+export declare function resolveGitHubToken(repoInfo: GitHubRepoInfo, tokenManager: ITokenManager | null, context: string, log?: DebugLog, envToken?: string): Promise<{
     token: string | undefined;
     skipped: boolean;
 }>;
+/**
+ * Check if an error message indicates an HTTP 404 response from the GitHub API.
+ */
+export declare function isHttp404Error(error: unknown): boolean;
 /**
  * Parse a JSON API response with a contextual error message.
  * Wraps JSON.parse so callers get "Failed to parse <context>: ..." instead of
  * a bare "Unexpected token" SyntaxError.
  */
-/**
- * Check if an error message indicates an HTTP 404 response from the GitHub API.
- */
-export declare function isHttp404Error(error: unknown): boolean;
 export declare function parseApiJson<T>(response: string, context: string): T;
 export {};

package/dist/shared/gh-api-utils.js

@@ -1,12 +1,13 @@
-import { escapeShellArg } from "../shared/shell-utils.js";
-import { withRetry } from "../shared/retry-utils.js";
-import { toErrorMessage } from "../shared/type-guards.js";
+import { escapeShellArg } from "./shell-utils.js";
+import { withRetry } from "./retry-utils.js";
+import { toErrorMessage } from "./type-guards.js";
+import { SyncError } from "./errors.js";
 /**
  * Get the hostname flag for gh commands.
  * Returns "--hostname HOST" for GHE, empty string for github.com.
  */
 export function getHostnameFlag(repoInfo) {
-    if (repoInfo.host && repoInfo.host !== "github.com") {
+    if (repoInfo.host !== "github.com") {
         return `--hostname ${escapeShellArg(repoInfo.host)}`;
     }
     return "";
@@ -22,7 +23,7 @@ export function buildTokenEnv(token) {
  * rather than shell-prefix string interpolation.
  */
 async function ghApiCall(method, endpoint, opts) {
-    const { executor, retries, apiOpts, payload, paginate } = opts;
+    const { executor, retries, cwd, apiOpts, payload, paginate } = opts;
     const args = ["gh", "api"];
     if (method !== "GET") {
         args.push("-X", method);
@@ -40,9 +41,13 @@ async function ghApiCall(method, endpoint, opts) {
         (method === "POST" || method === "PUT" || method === "PATCH")) {
         const payloadJson = JSON.stringify(payload);
         const command = `echo ${escapeShellArg(payloadJson)} | ${baseCommand} --input -`;
-        return await withRetry(() => executor.exec(command, process.cwd(), { env }), { retries });
+        return await withRetry(() => executor.exec(command, cwd, { env }), {
+            retries,
+        });
     }
-    return await withRetry(() => executor.exec(baseCommand, process.cwd(), { env }), { retries });
+    return await withRetry(() => executor.exec(baseCommand, cwd, { env }), {
+        retries,
+    });
 }
 /**
  * Encapsulates executor + retries for GitHub API calls.
@@ -51,24 +56,27 @@ async function ghApiCall(method, endpoint, opts) {
 export class GhApiClient {
     executor;
     retries;
-    constructor(executor, retries) {
+    cwd;
+    constructor(executor, retries, cwd) {
         this.executor = executor;
         this.retries = retries;
+        this.cwd = cwd;
     }
-    async call(method, endpoint, payload, options, paginate) {
+    async call(method, endpoint, params) {
         return ghApiCall(method, endpoint, {
             executor: this.executor,
             retries: this.retries,
-            apiOpts: options,
-            payload,
-            paginate,
+            cwd: this.cwd,
+            apiOpts: params?.options,
+            payload: params?.payload,
+            paginate: params?.paginate,
         });
     }
 }
 /**
- * Resolve a GitHub token for a repo: GitHub App token → GH_TOKEN env fallback.
+ * Resolve a GitHub token for a repo: GitHub App token → envToken fallback.
  * Returns { token, skipped } where skipped=true means no App installation found
- * and no GH_TOKEN is available. Both sync and settings paths use this function.
+ * for this owner (token will be undefined). Both sync and settings paths use this.
  */
 export async function resolveGitHubToken(repoInfo, tokenManager, context, log, envToken) {
     try {
@@ -81,27 +89,30 @@ export async function resolveGitHubToken(repoInfo, tokenManager, context, log, e
         return { token: appToken ?? envToken, skipped: false };
     }
     catch (error) {
-        log?.debug(`GitHub App token resolution failed for ${context}: ${toErrorMessage(error)}; falling back to GH_TOKEN`);
+        const fallbackDesc = envToken
+            ? "falling back to GH_TOKEN"
+            : "no fallback token available";
+        log?.debug(`GitHub App token resolution failed for ${context}: ${toErrorMessage(error)}; ${fallbackDesc}`);
         return { token: envToken, skipped: false };
     }
 }
-/**
- * Parse a JSON API response with a contextual error message.
- * Wraps JSON.parse so callers get "Failed to parse <context>: ..." instead of
- * a bare "Unexpected token" SyntaxError.
- */
 /**
  * Check if an error message indicates an HTTP 404 response from the GitHub API.
  */
 export function isHttp404Error(error) {
     return toErrorMessage(error).includes("HTTP 404");
 }
+/**
+ * Parse a JSON API response with a contextual error message.
+ * Wraps JSON.parse so callers get "Failed to parse <context>: ..." instead of
+ * a bare "Unexpected token" SyntaxError.
+ */
 export function parseApiJson(response, context) {
     try {
         return JSON.parse(response);
     }
-    catch {
+    catch (error) {
         const preview = response.slice(0, 200);
-        throw new Error(`Failed to parse ${context}: ${preview}`);
+        throw new SyncError(`Failed to parse ${context}: ${toErrorMessage(error)} — ${preview}`);
     }
 }

package/dist/shared/index.d.ts

@@ -1,8 +1,15 @@
-export { Logger, logger, type ILogger } from "./logger.js";
+export { Logger, NO_OP_DEBUG_LOG, type ILogger, type DebugLog, type DebugWarnLog, type DebugInfoLog, type DebugInfoWarnLog, } from "./logger.js";
 export { withRetry, isPermanentError, isTransientError, DEFAULT_PERMANENT_ERROR_PATTERNS, } from "./retry-utils.js";
-export { ShellCommandExecutor, defaultExecutor, type ICommandExecutor, } from "./command-executor.js";
+export { ShellCommandExecutor, type ICommandExecutor, } from "./command-executor.js";
 export { escapeShellArg, escapeRegExp } from "./shell-utils.js";
 export { sanitizeCredentials } from "./sanitize-utils.js";
 export { interpolateEnvVars, interpolateContent, type EnvInterpolationOptions, } from "./env.js";
 export { generateWorkspaceName } from "./workspace-utils.js";
 export { detectRepoType, parseGitUrl, getRepoDisplayName, isGitHubRepo, isAzureDevOpsRepo, isGitLabRepo, type RepoInfo, type GitHubRepoInfo, type AzureDevOpsRepoInfo, type GitLabRepoInfo, } from "./repo-detector.js";
+export { ValidationError, GraphQLApiError, SyncError, LifecycleError, } from "./errors.js";
+export { formatStatusBadge, type FileStatus } from "./file-status.js";
+export { GhApiClient, getHostnameFlag, buildTokenEnv, resolveGitHubToken, isHttp404Error, parseApiJson, type GhApiOptions, } from "./gh-api-utils.js";
+export { interpolateString, interpolateValue, type InterpolationConfig, } from "./interpolation-engine.js";
+export { camelToSnake } from "./string-utils.js";
+export { isPlainObject, toErrorMessage, safeCleanup } from "./type-guards.js";
+export { interpolateXfgContent, type XfgTemplateContext, } from "./xfg-template.js";

package/dist/shared/index.js

@@ -1,9 +1,9 @@
 // Logging
-export { Logger, logger } from "./logger.js";
+export { Logger, NO_OP_DEBUG_LOG, } from "./logger.js";
 // Retry utilities
 export { withRetry, isPermanentError, isTransientError, DEFAULT_PERMANENT_ERROR_PATTERNS, } from "./retry-utils.js";
 // Command execution
-export { ShellCommandExecutor, defaultExecutor, } from "./command-executor.js";
+export { ShellCommandExecutor, } from "./command-executor.js";
 // Shell utilities
 export { escapeShellArg, escapeRegExp } from "./shell-utils.js";
 // Sanitization
@@ -14,3 +14,17 @@ export { interpolateEnvVars, interpolateContent, } from "./env.js";
 export { generateWorkspaceName } from "./workspace-utils.js";
 // Repository detection
 export { detectRepoType, parseGitUrl, getRepoDisplayName, isGitHubRepo, isAzureDevOpsRepo, isGitLabRepo, } from "./repo-detector.js";
+// Errors
+export { ValidationError, GraphQLApiError, SyncError, LifecycleError, } from "./errors.js";
+// File status
+export { formatStatusBadge } from "./file-status.js";
+// GitHub API utilities
+export { GhApiClient, getHostnameFlag, buildTokenEnv, resolveGitHubToken, isHttp404Error, parseApiJson, } from "./gh-api-utils.js";
+// Interpolation engine
+export { interpolateString, interpolateValue, } from "./interpolation-engine.js";
+// String utilities
+export { camelToSnake } from "./string-utils.js";
+// Type guards
+export { isPlainObject, toErrorMessage, safeCleanup } from "./type-guards.js";
+// XFG templating
+export { interpolateXfgContent, } from "./xfg-template.js";

package/dist/shared/logger.d.ts

@@ -1,4 +1,24 @@
 import { FileStatus } from "./file-status.js";
+/** Minimal log interface: debug only. */
+export type DebugLog = {
+    debug(msg: string): void;
+};
+/** Log interface: debug + warn. */
+export type DebugWarnLog = {
+    debug(msg: string): void;
+    warn(msg: string): void;
+};
+/** Log interface: debug + info. */
+export type DebugInfoLog = {
+    debug(msg: string): void;
+    info(msg: string): void;
+};
+/** Log interface: debug + info + warn. */
+export type DebugInfoWarnLog = {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+};
 export interface ILogger {
     log(message: string): void;
     info(message: string): void;
@@ -13,7 +33,9 @@ export interface ILogger {
     error(current: number, repoName: string, error: string): void;
 }
 export declare class Logger implements ILogger {
+    private readonly debugEnabled;
     private stats;
+    constructor(debugEnabled?: boolean);
     log(message: string): void;
     setTotal(total: number): void;
     progress(current: number, repoName: string, message: string): void;
@@ -33,4 +55,5 @@ export declare class Logger implements ILogger {
      */
     diffSummary(newCount: number, modifiedCount: number, unchangedCount: number, deletedCount?: number): void;
 }
-export declare const logger: Logger;
+/** No-op debug logger for use as a fallback when logging is optional. */
+export declare const NO_OP_DEBUG_LOG: DebugLog;

package/dist/shared/logger.js

@@ -1,12 +1,16 @@
 import chalk from "chalk";
 import { formatStatusBadge } from "./file-status.js";
 export class Logger {
+    debugEnabled;
     stats = {
         total: 0,
         succeeded: 0,
         failed: 0,
         skipped: 0,
     };
+    constructor(debugEnabled) {
+        this.debugEnabled = debugEnabled ?? false;
+    }
     log(message) {
         console.log(message);
     }
@@ -24,7 +28,7 @@ export class Logger {
         console.log(chalk.yellow(`    ⚠ ${message}`));
     }
     debug(message) {
-        if (process.env.DEBUG || process.env.XFG_DEBUG) {
+        if (this.debugEnabled) {
             console.log(chalk.dim(`    [debug] ${message}`));
         }
     }
@@ -65,7 +69,7 @@ export class Logger {
             parts.push(chalk.green(`${newCount} new`));
         if (modifiedCount > 0)
             parts.push(chalk.yellow(`${modifiedCount} modified`));
-        if (deletedCount && deletedCount > 0)
+        if ((deletedCount ?? 0) > 0)
             parts.push(chalk.red(`${deletedCount} deleted`));
         if (unchangedCount > 0)
             parts.push(chalk.gray(`${unchangedCount} unchanged`));
@@ -74,4 +78,5 @@ export class Logger {
         }
     }
 }
-export const logger = new Logger();
+/** No-op debug logger for use as a fallback when logging is optional. */
+export const NO_OP_DEBUG_LOG = { debug() { } };

package/dist/shared/repo-detector.js

@@ -1,3 +1,4 @@
+import { ValidationError } from "./errors.js";
 // Type guards
 export function isGitHubRepo(info) {
     return info.type === "github";
@@ -14,7 +15,7 @@ export function isGitLabRepo(info) {
  */
 export function assertGitHubRepo(repoInfo, context) {
     if (!isGitHubRepo(repoInfo)) {
-        throw new Error(`${context} requires GitHub repositories. Got: ${repoInfo.type}`);
+        throw new ValidationError(`${context} requires GitHub repositories. Got: ${repoInfo.type}`);
     }
 }
 /**
@@ -23,7 +24,7 @@ export function assertGitHubRepo(repoInfo, context) {
  */
 export function assertAzureDevOpsRepo(repoInfo, context) {
     if (!isAzureDevOpsRepo(repoInfo)) {
-        throw new Error(`${context} requires Azure DevOps repositories. Got: ${repoInfo.type}`);
+        throw new ValidationError(`${context} requires Azure DevOps repositories. Got: ${repoInfo.type}`);
     }
 }
 /**
@@ -32,12 +33,9 @@ export function assertAzureDevOpsRepo(repoInfo, context) {
  */
 export function assertGitLabRepo(repoInfo, context) {
     if (!isGitLabRepo(repoInfo)) {
-        throw new Error(`${context} requires GitLab repositories. Got: ${repoInfo.type}`);
+        throw new ValidationError(`${context} requires GitLab repositories. Got: ${repoInfo.type}`);
     }
 }
-/**
- * Extract hostname from a git URL.
- */
 function extractHostFromUrl(gitUrl) {
     // SSH: git@hostname:path
     const sshMatch = gitUrl.match(/^git@([^:]+):/);
@@ -116,7 +114,7 @@ export function detectRepoType(gitUrl, context) {
         return "gitlab";
     }
     // Throw for unrecognized URL formats
-    throw new Error(`Unrecognized git URL format: ${gitUrl}. Supported formats: GitHub (git@github.com: or https://github.com/), Azure DevOps (git@ssh.dev.azure.com: or https://dev.azure.com/), and GitLab (git@gitlab.com: or https://gitlab.com/)`);
+    throw new ValidationError(`Unrecognized git URL format: ${gitUrl}. Supported formats: GitHub (git@github.com: or https://github.com/), Azure DevOps (git@ssh.dev.azure.com: or https://dev.azure.com/), and GitLab (git@gitlab.com: or https://gitlab.com/)`);
 }
 export function parseGitUrl(gitUrl, context) {
     const type = detectRepoType(gitUrl, context);
@@ -155,7 +153,7 @@ function parseGitHubUrl(gitUrl, host) {
             host,
         };
     }
-    throw new Error(`Unable to parse GitHub URL: ${gitUrl}`);
+    throw new ValidationError(`Unable to parse GitHub URL: ${gitUrl}`);
 }
 function parseAzureDevOpsUrl(gitUrl) {
     // Handle SSH format: git@ssh.dev.azure.com:v3/organization/project/repo
@@ -184,7 +182,7 @@ function parseAzureDevOpsUrl(gitUrl) {
             project: httpsMatch[2],
         };
     }
-    throw new Error(`Unable to parse Azure DevOps URL: ${gitUrl}`);
+    throw new ValidationError(`Unable to parse Azure DevOps URL: ${gitUrl}`);
 }
 function parseGitLabUrl(gitUrl) {
     // Handle SSH format: git@gitlab.com:owner/repo.git or git@gitlab.com:org/group/repo.git
@@ -203,13 +201,13 @@ function parseGitLabUrl(gitUrl) {
         const fullPath = httpsMatch[2];
         return parseGitLabPath(gitUrl, host, fullPath);
     }
-    throw new Error(`Unable to parse GitLab URL: ${gitUrl}`);
+    throw new ValidationError(`Unable to parse GitLab URL: ${gitUrl}`);
 }
 function parseGitLabPath(gitUrl, host, fullPath) {
     // Split path into segments: org/group/subgroup/repo -> [org, group, subgroup, repo]
     const segments = fullPath.split("/");
     if (segments.length < 2) {
-        throw new Error(`Unable to parse GitLab URL: ${gitUrl}`);
+        throw new ValidationError(`Unable to parse GitLab URL: ${gitUrl}`);
     }
     // Last segment is repo, everything else is namespace
     const repo = segments[segments.length - 1];

package/dist/shared/retry-utils.d.ts

@@ -17,21 +17,19 @@ interface RetryOptions {
     permanentErrorPatterns?: RegExp[];
     /** Custom transient error patterns (defaults to DEFAULT_TRANSIENT_ERROR_PATTERNS) */
     transientErrorPatterns?: RegExp[];
+    /** Logger for retry messages (defaults to no logging) */
+    log?: {
+        info(msg: string): void;
+    };
 }
 /**
  * Classifies an error as permanent (should not retry) or transient (should retry).
- * @param error The error to classify
- * @param patterns Custom patterns to use (defaults to DEFAULT_PERMANENT_ERROR_PATTERNS)
- * @returns true if the error is permanent, false if it might be transient
  */
 export declare function isPermanentError(error: unknown, patterns?: RegExp[]): boolean;
 /**
  * Checks if an error matches known transient patterns.
- * @param error The error to check
- * @param patterns Custom patterns to use (defaults to DEFAULT_TRANSIENT_ERROR_PATTERNS)
- * @returns true if the error appears to be transient
  */
-export declare function isTransientError(error: Error, patterns?: RegExp[]): boolean;
+export declare function isTransientError(error: unknown, patterns?: RegExp[]): boolean;
 /**
  * Wraps an async operation with retry logic using exponential backoff.
  * Automatically classifies errors and aborts retries for permanent failures.

package/dist/shared/retry-utils.js

@@ -1,7 +1,6 @@
 import pRetry, { AbortError } from "p-retry";
-import { logger } from "./logger.js";
 import { sanitizeCredentials } from "./sanitize-utils.js";
-import { ValidationError } from "../config/errors.js";
+import { ValidationError } from "./errors.js";
 /**
  * Core permanent error patterns shared across all strategies (API, GraphQL, CLI).
  * Auth failures, permission issues, and resource-not-found errors.
@@ -68,9 +67,6 @@ const DEFAULT_TRANSIENT_ERROR_PATTERNS = [
 ];
 /**
  * Classifies an error as permanent (should not retry) or transient (should retry).
- * @param error The error to classify
- * @param patterns Custom patterns to use (defaults to DEFAULT_PERMANENT_ERROR_PATTERNS)
- * @returns true if the error is permanent, false if it might be transient
  */
 export function isPermanentError(error, patterns = DEFAULT_PERMANENT_ERROR_PATTERNS) {
     // Validation errors are always permanent — no point retrying bad input
@@ -90,12 +86,9 @@ export function isPermanentError(error, patterns = DEFAULT_PERMANENT_ERROR_PATTE
 }
 /**
  * Checks if an error matches known transient patterns.
- * @param error The error to check
- * @param patterns Custom patterns to use (defaults to DEFAULT_TRANSIENT_ERROR_PATTERNS)
- * @returns true if the error appears to be transient
  */
 export function isTransientError(error, patterns = DEFAULT_TRANSIENT_ERROR_PATTERNS) {
-    const message = error.message;
+    const message = error instanceof Error ? error.message : String(error ?? "");
     const stderr = error.stderr?.toString() ?? "";
     const combined = `${message} ${stderr}`;
     for (const pattern of patterns) {
@@ -135,7 +128,7 @@ export async function withRetry(fn, options) {
             // Only log if this isn't the last attempt
             if (context.retriesLeft > 0) {
                 const msg = sanitizeCredentials(context.error.message) || "Unknown error";
-                logger.info(`Attempt ${context.attemptNumber}/${retries + 1} failed: ${msg}. Retrying...`);
+                options?.log?.info(`Attempt ${context.attemptNumber}/${retries + 1} failed: ${msg}. Retrying...`);
                 options?.onRetry?.(context.error, context.attemptNumber);
             }
         },