opkg 0.9.0 → 0.9.2

package/packages/core/dist/utils/git-spec.d.ts

@@ -0,0 +1,19 @@
+export interface GitSpec {
+    url: string;
+    ref?: string;
+    subdirectory?: string;
+}
+/**
+ * Parse git/github specs:
+ * - github:owner/repo[#ref][&subdirectory=path] -> https://github.com/owner/repo.git
+ * - git:<url>[#ref][&subdirectory=path] -> uses provided url
+ *
+ * Examples:
+ * - github:anthropics/claude-code
+ * - github:anthropics/claude-code#main
+ * - github:anthropics/claude-code#subdirectory=plugins/commit-commands
+ * - github:anthropics/claude-code#main&subdirectory=plugins/commit-commands
+ * - git:https://github.com/user/repo.git#v1.0.0&subdirectory=packages/plugin-a
+ */
+export declare function parseGitSpec(raw: string): GitSpec | null;
+//# sourceMappingURL=git-spec.d.ts.map

package/packages/core/dist/utils/git-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-spec.d.ts","sourceRoot":"","sources":["../../src/utils/git-spec.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAsFD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAExD"}

package/packages/core/dist/utils/git-spec.js

@@ -0,0 +1,96 @@
+import { ValidationError } from './errors.js';
+function parseGithubShorthand(raw) {
+    if (!raw.startsWith('github:'))
+        return null;
+    const remainder = raw.slice('github:'.length);
+    // Split on '#' to get repo part and ref/options
+    const [repoPart, hashPart] = remainder.split('#', 2);
+    const [owner, repo] = repoPart.split('/');
+    if (!owner || !repo) {
+        throw new ValidationError(`Invalid github spec '${raw}'. Expected github:owner/repo[#ref][&subdirectory=path]`);
+    }
+    const url = `https://github.com/${owner}/${repo}.git`;
+    const result = { url };
+    // Parse hash part for ref and subdirectory
+    if (hashPart) {
+        const { ref, subdirectory } = parseHashPart(hashPart);
+        if (ref)
+            result.ref = ref;
+        if (subdirectory)
+            result.subdirectory = subdirectory;
+    }
+    return result;
+}
+function parseGitUrl(raw) {
+    if (!raw.startsWith('git:'))
+        return null;
+    const remainder = raw.slice('git:'.length);
+    const [url, hashPart] = remainder.split('#', 2);
+    if (!url) {
+        throw new ValidationError(`Invalid git spec '${raw}'. Expected git:<url>[#ref][&subdirectory=path]`);
+    }
+    const result = { url };
+    // Parse hash part for ref and subdirectory
+    if (hashPart) {
+        const { ref, subdirectory } = parseHashPart(hashPart);
+        if (ref)
+            result.ref = ref;
+        if (subdirectory)
+            result.subdirectory = subdirectory;
+    }
+    return result;
+}
+/**
+ * Parse the hash part of a git spec to extract ref and subdirectory.
+ *
+ * Supported formats:
+ * - #ref
+ * - #subdirectory=path
+ * - #ref&subdirectory=path
+ *
+ * Examples:
+ * - #main -> { ref: 'main' }
+ * - #subdirectory=plugins/my-plugin -> { subdirectory: 'plugins/my-plugin' }
+ * - #v1.0.0&subdirectory=plugins/my-plugin -> { ref: 'v1.0.0', subdirectory: 'plugins/my-plugin' }
+ */
+function parseHashPart(hashPart) {
+    const result = {};
+    // Split on '&' to get ref and options
+    const parts = hashPart.split('&');
+    for (const part of parts) {
+        if (part.includes('=')) {
+            // It's a key=value option
+            const [key, value] = part.split('=', 2);
+            if (key === 'subdirectory') {
+                result.subdirectory = value;
+            }
+            else {
+                throw new ValidationError(`Unknown git spec option: ${key}. Supported: subdirectory`);
+            }
+        }
+        else {
+            // It's the ref (branch/tag/sha)
+            if (result.ref) {
+                throw new ValidationError(`Multiple refs specified in git spec: ${hashPart}`);
+            }
+            result.ref = part;
+        }
+    }
+    return result;
+}
+/**
+ * Parse git/github specs:
+ * - github:owner/repo[#ref][&subdirectory=path] -> https://github.com/owner/repo.git
+ * - git:<url>[#ref][&subdirectory=path] -> uses provided url
+ *
+ * Examples:
+ * - github:anthropics/claude-code
+ * - github:anthropics/claude-code#main
+ * - github:anthropics/claude-code#subdirectory=plugins/commit-commands
+ * - github:anthropics/claude-code#main&subdirectory=plugins/commit-commands
+ * - git:https://github.com/user/repo.git#v1.0.0&subdirectory=packages/plugin-a
+ */
+export function parseGitSpec(raw) {
+    return parseGithubShorthand(raw) ?? parseGitUrl(raw);
+}
+//# sourceMappingURL=git-spec.js.map

package/packages/core/dist/utils/git-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-spec.js","sourceRoot":"","sources":["../../src/utils/git-spec.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/utils/git-url-detection.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Modern git source detection and parsing.
+ * Supports:
+ * - GitHub shorthand (gh@owner/repo[/path])
+ * - GitHub web URLs (https://github.com/owner/repo/tree/ref/path)
+ * - Generic git URLs with hash fragments (#ref&path=x)
+ * - Legacy prefixes (github:, git:) with deprecation warnings
+ */
+/**
+ * Parsed git source specification.
+ */
+export interface GitSpec {
+    url: string;
+    ref?: string;
+    path?: string;
+}
+/**
+ * Detect and parse git sources from user input.
+ * Returns null if input is not a git source.
+ *
+ * Detection priority (by user intent):
+ * 1. GitHub shorthand (gh@) - new explicit syntax
+ * 2. URL protocols (https://, http://, git://, git@) - direct URLs
+ * 3. Git file extension (.git) - any URL ending with .git
+ * 4. Legacy prefixes (github:, git:) - deprecated, with warnings
+ *
+ * Implementation order (to avoid conflicts):
+ * - Legacy prefixes checked first (they mask underlying URL patterns)
+ * - GitHub shorthand (explicit new syntax)
+ * - GitHub URLs (specific pattern matching)
+ * - Generic git URLs (catch-all)
+ *
+ * @param input - Raw user input
+ * @returns Parsed GitSpec or null if not a git source
+ */
+export declare function detectGitSource(input: string): GitSpec | null;
+/**
+ * Parse GitHub shorthand format: gh@owner/repo[/path]
+ *
+ * Examples:
+ * - gh@anthropics/claude-code
+ * - gh@user/repo/plugins/x
+ *
+ * @param input - Raw input string
+ * @returns GitSpec or null if not GitHub shorthand
+ */
+export declare function parseGitHubShorthand(input: string): GitSpec | null;
+/**
+ * Parse GitHub web URLs.
+ *
+ * Supported formats:
+ * - https://github.com/owner/repo
+ * - https://github.com/owner/repo.git
+ * - https://github.com/owner/repo/tree/ref
+ * - https://github.com/owner/repo/tree/ref/path
+ *
+ * @param input - Raw input string
+ * @returns GitSpec or null if not a GitHub URL
+ */
+export declare function parseGitHubUrl(input: string): GitSpec | null;
+/**
+ * Parse generic git URLs with hash fragments.
+ *
+ * Supported formats:
+ * - https://host/path.git
+ * - git://host/path
+ * - git@host:path.git
+ * - <any-git-url>#<ref>
+ * - <any-git-url>#<ref>&path=<path>
+ * - <any-git-url>#path=<path>
+ *
+ * @param input - Raw input string
+ * @returns GitSpec or null if not a git URL
+ */
+export declare function parseGenericGitUrl(input: string): GitSpec | null;
+/**
+ * Check if input looks like a git URL.
+ *
+ * Detection criteria:
+ * - Starts with git protocol: https://, http://, git://, git@
+ * - Ends with .git extension
+ */
+export declare function isGitUrl(input: string): boolean;
+/**
+ * Normalize GitHub owner/repo to full git URL.
+ *
+ * @param owner - GitHub username or org
+ * @param repo - Repository name
+ * @returns Normalized GitHub git URL
+ */
+export declare function normalizeGitHubUrl(owner: string, repo: string): string;
+//# sourceMappingURL=git-url-detection.d.ts.map

package/packages/core/dist/utils/git-url-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-url-detection.d.ts","sourceRoot":"","sources":["../../src/utils/git-url-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA8B7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAwClE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA6E5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAsBhE;AA8HD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQ/C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAItE"}

package/packages/core/dist/utils/git-url-detection.js

@@ -0,0 +1,327 @@
+/**
+ * Modern git source detection and parsing.
+ * Supports:
+ * - GitHub shorthand (gh@owner/repo[/path])
+ * - GitHub web URLs (https://github.com/owner/repo/tree/ref/path)
+ * - Generic git URLs with hash fragments (#ref&path=x)
+ * - Legacy prefixes (github:, git:) with deprecation warnings
+ */
+import { ValidationError } from './errors.js';
+import { logger } from './logger.js';
+/**
+ * Detect and parse git sources from user input.
+ * Returns null if input is not a git source.
+ *
+ * Detection priority (by user intent):
+ * 1. GitHub shorthand (gh@) - new explicit syntax
+ * 2. URL protocols (https://, http://, git://, git@) - direct URLs
+ * 3. Git file extension (.git) - any URL ending with .git
+ * 4. Legacy prefixes (github:, git:) - deprecated, with warnings
+ *
+ * Implementation order (to avoid conflicts):
+ * - Legacy prefixes checked first (they mask underlying URL patterns)
+ * - GitHub shorthand (explicit new syntax)
+ * - GitHub URLs (specific pattern matching)
+ * - Generic git URLs (catch-all)
+ *
+ * @param input - Raw user input
+ * @returns Parsed GitSpec or null if not a git source
+ */
+export function detectGitSource(input) {
+    if (!input || typeof input !== 'string') {
+        return null;
+    }
+    // Check legacy prefixes first (they hide the URL underneath)
+    const legacy = parseLegacyPrefix(input);
+    if (legacy) {
+        return legacy;
+    }
+    // GitHub shorthand (gh@owner/repo)
+    const ghShorthand = parseGitHubShorthand(input);
+    if (ghShorthand) {
+        return ghShorthand;
+    }
+    // GitHub URLs (extract ref/path from URL structure)
+    const ghUrl = parseGitHubUrl(input);
+    if (ghUrl) {
+        return ghUrl;
+    }
+    // Generic git URLs (with hash fragments)
+    const genericGit = parseGenericGitUrl(input);
+    if (genericGit) {
+        return genericGit;
+    }
+    return null;
+}
+/**
+ * Parse GitHub shorthand format: gh@owner/repo[/path]
+ *
+ * Examples:
+ * - gh@anthropics/claude-code
+ * - gh@user/repo/plugins/x
+ *
+ * @param input - Raw input string
+ * @returns GitSpec or null if not GitHub shorthand
+ */
+export function parseGitHubShorthand(input) {
+    if (!input.startsWith('gh@')) {
+        return null;
+    }
+    const remainder = input.slice(3); // Remove 'gh@'
+    if (!remainder) {
+        throw new ValidationError(`Invalid GitHub shorthand 'gh@'. Expected format: gh@owner/repo[/path]\n\n` +
+            `Examples:\n` +
+            `  gh@anthropics/claude-code\n` +
+            `  gh@user/repo/plugins/my-plugin`);
+    }
+    const segments = remainder.split('/').filter(s => s.length > 0);
+    if (segments.length < 2) {
+        throw new ValidationError(`Invalid GitHub shorthand '${input}'. Expected format: gh@owner/repo[/path]\n\n` +
+            `Examples:\n` +
+            `  gh@anthropics/claude-code\n` +
+            `  gh@user/repo/plugins/my-plugin`);
+    }
+    const owner = segments[0];
+    const repo = segments[1];
+    const url = normalizeGitHubUrl(owner, repo);
+    const path = segments.length > 2 ? segments.slice(2).join('/') : undefined;
+    logger.debug('Parsed GitHub shorthand', { input, owner, repo, path, url });
+    return {
+        url,
+        ref: undefined, // GitHub shorthand always uses default branch
+        path
+    };
+}
+/**
+ * Parse GitHub web URLs.
+ *
+ * Supported formats:
+ * - https://github.com/owner/repo
+ * - https://github.com/owner/repo.git
+ * - https://github.com/owner/repo/tree/ref
+ * - https://github.com/owner/repo/tree/ref/path
+ *
+ * @param input - Raw input string
+ * @returns GitSpec or null if not a GitHub URL
+ */
+export function parseGitHubUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        return null;
+    }
+    // Must be github.com
+    if (url.hostname !== 'github.com') {
+        return null;
+    }
+    const segments = url.pathname.split('/').filter(s => s.length > 0);
+    if (segments.length < 2) {
+        throw new ValidationError(`Invalid GitHub URL. Expected: https://github.com/owner/repo\n\n` +
+            `Got: ${input}`);
+    }
+    const owner = segments[0];
+    let repo = segments[1];
+    // Strip .git suffix from repo if present
+    if (repo.endsWith('.git')) {
+        repo = repo.slice(0, -4);
+    }
+    const normalizedUrl = normalizeGitHubUrl(owner, repo);
+    let ref;
+    let path;
+    // Check for /tree/ or /blob/ paths
+    if (segments.length > 2) {
+        const pathType = segments[2];
+        if (pathType === 'blob') {
+            throw new ValidationError(`Cannot install from single file URL\n\n` +
+                `You provided:\n` +
+                `  ${input}\n\n` +
+                `To install a package, use:\n` +
+                `  • Repository: https://github.com/${owner}/${repo}\n` +
+                `  • With branch: https://github.com/${owner}/${repo}/tree/main\n` +
+                `  • Subdirectory: https://github.com/${owner}/${repo}/tree/main/plugins/x\n` +
+                `  • Shorthand: gh@${owner}/${repo}/plugins/x`);
+        }
+        if (pathType === 'tree') {
+            if (segments.length < 4) {
+                throw new ValidationError(`Invalid GitHub URL. Ref is required after /tree/\n\n` +
+                    `Got: ${input}\n\n` +
+                    `Expected: https://github.com/${owner}/${repo}/tree/<ref>[/path]`);
+            }
+            ref = decodeURIComponent(segments[3]);
+            // Path is everything after the ref
+            if (segments.length > 4) {
+                path = segments.slice(4).map(s => decodeURIComponent(s)).join('/');
+            }
+        }
+    }
+    logger.debug('Parsed GitHub URL', { input, owner, repo, ref, path, url: normalizedUrl });
+    return {
+        url: normalizedUrl,
+        ref,
+        path
+    };
+}
+/**
+ * Parse generic git URLs with hash fragments.
+ *
+ * Supported formats:
+ * - https://host/path.git
+ * - git://host/path
+ * - git@host:path.git
+ * - <any-git-url>#<ref>
+ * - <any-git-url>#<ref>&path=<path>
+ * - <any-git-url>#path=<path>
+ *
+ * @param input - Raw input string
+ * @returns GitSpec or null if not a git URL
+ */
+export function parseGenericGitUrl(input) {
+    if (!isGitUrl(input)) {
+        return null;
+    }
+    // Split by # to separate base URL and hash fragment
+    const [baseUrl, hashPart] = input.split('#', 2);
+    const result = {
+        url: baseUrl
+    };
+    // Parse hash fragment if present
+    if (hashPart) {
+        const { ref, path } = parseHashFragment(hashPart, input);
+        if (ref)
+            result.ref = ref;
+        if (path)
+            result.path = path;
+    }
+    logger.debug('Parsed generic git URL', { input, ...result });
+    return result;
+}
+/**
+ * Parse legacy prefix formats with deprecation warnings.
+ *
+ * Supported formats:
+ * - github:owner/repo[#ref][&subdirectory=path]
+ * - git:<url>[#ref][&subdirectory=path]
+ *
+ * @param input - Raw input string
+ * @returns GitSpec or null if not using legacy prefix
+ */
+function parseLegacyPrefix(input) {
+    // Check for github: prefix
+    if (input.startsWith('github:')) {
+        logger.warn(`⚠️  The 'github:' prefix is deprecated. Use 'gh@user/repo' instead.`);
+        const remainder = input.slice(7); // Remove 'github:'
+        const [repoPart, hashPart] = remainder.split('#', 2);
+        const [owner, repo] = repoPart.split('/');
+        if (!owner || !repo) {
+            throw new ValidationError(`Invalid github spec '${input}'. Expected github:owner/repo[#ref][&subdirectory=path]`);
+        }
+        const url = normalizeGitHubUrl(owner, repo);
+        const result = { url };
+        if (hashPart) {
+            const { ref, path } = parseHashFragment(hashPart, input);
+            if (ref)
+                result.ref = ref;
+            if (path)
+                result.path = path;
+        }
+        return result;
+    }
+    // Check for git: prefix
+    if (input.startsWith('git:')) {
+        logger.warn(`⚠️  The 'git:' prefix is deprecated. Use the URL directly.`);
+        const remainder = input.slice(4); // Remove 'git:'
+        const [url, hashPart] = remainder.split('#', 2);
+        if (!url) {
+            throw new ValidationError(`Invalid git spec '${input}'. Expected git:<url>[#ref][&subdirectory=path]`);
+        }
+        const result = { url };
+        if (hashPart) {
+            const { ref, path } = parseHashFragment(hashPart, input);
+            if (ref)
+                result.ref = ref;
+            if (path)
+                result.path = path;
+        }
+        return result;
+    }
+    return null;
+}
+/**
+ * Parse hash fragment for ref and path parameters.
+ *
+ * Supported formats:
+ * - #<ref>
+ * - #path=<path>
+ * - #subdirectory=<path> (backward compat, no warning)
+ * - #<ref>&path=<path>
+ * - #<ref>&subdirectory=<path>
+ *
+ * @param hashPart - Hash fragment (without #)
+ * @param fullInput - Full input for error messages
+ * @returns Object with ref and path
+ */
+function parseHashFragment(hashPart, fullInput) {
+    const result = {};
+    // Split by & to get parts
+    const parts = hashPart.split('&');
+    for (const part of parts) {
+        if (!part)
+            continue;
+        if (part.includes('=')) {
+            // It's a key=value parameter
+            const eqIndex = part.indexOf('=');
+            const key = part.slice(0, eqIndex);
+            const value = part.slice(eqIndex + 1);
+            if (key === 'path' || key === 'subdirectory') {
+                result.path = value;
+            }
+            else {
+                throw new ValidationError(`Invalid hash fragment '#${hashPart}'\n\n` +
+                    `Unknown parameter: ${key}\n\n` +
+                    `Supported parameters:\n` +
+                    `  • ref (unnamed): #main\n` +
+                    `  • path: #path=plugins/x\n` +
+                    `  • combined: #main&path=plugins/x`);
+            }
+        }
+        else {
+            // It's the ref (branch/tag/sha)
+            if (result.ref) {
+                throw new ValidationError(`Multiple refs specified in hash fragment\n\n` +
+                    `Got: #${hashPart}\n\n` +
+                    `Use only one ref: #main or #v1.0.0`);
+            }
+            result.ref = part;
+        }
+    }
+    return result;
+}
+/**
+ * Check if input looks like a git URL.
+ *
+ * Detection criteria:
+ * - Starts with git protocol: https://, http://, git://, git@
+ * - Ends with .git extension
+ */
+export function isGitUrl(input) {
+    return (input.startsWith('https://') ||
+        input.startsWith('http://') ||
+        input.startsWith('git://') ||
+        input.startsWith('git@') ||
+        input.endsWith('.git'));
+}
+/**
+ * Normalize GitHub owner/repo to full git URL.
+ *
+ * @param owner - GitHub username or org
+ * @param repo - Repository name
+ * @returns Normalized GitHub git URL
+ */
+export function normalizeGitHubUrl(owner, repo) {
+    // Ensure repo doesn't have .git suffix for consistent handling
+    const cleanRepo = repo.endsWith('.git') ? repo.slice(0, -4) : repo;
+    return `https://github.com/${owner}/${cleanRepo}.git`;
+}
+//# sourceMappingURL=git-url-detection.js.map

package/packages/core/dist/utils/git-url-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-url-detection.js","sourceRoot":"","sources":["../../src/utils/git-url-detection.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/utils/git-url-parser.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Parsed Git URL components.
+ */
+export interface ParsedGitUrl {
+    host: string;
+    owner: string;
+    repo: string;
+    protocol: 'https' | 'ssh' | 'git';
+    normalized: string;
+}
+/**
+ * GitHub-specific metadata extracted from URL.
+ */
+export interface GitHubInfo {
+    username: string;
+    repo: string;
+}
+/**
+ * Normalize a Git URL for consistent hashing.
+ * - Converts to lowercase
+ * - Removes .git suffix
+ * - Normalizes GitHub SSH to HTTPS format
+ */
+export declare function normalizeGitUrl(url: string): string;
+/**
+ * Parse a Git URL into its components.
+ * Supports various formats:
+ * - https://github.com/owner/repo.git
+ * - git@github.com:owner/repo.git
+ * - https://gitlab.com/group/subgroup/repo.git
+ * - ssh://git@bitbucket.org/owner/repo.git
+ */
+export declare function parseGitUrl(url: string): ParsedGitUrl;
+/**
+ * Extract GitHub metadata from a Git URL.
+ * Returns null if the URL is not a GitHub URL.
+ */
+export declare function extractGitHubInfo(url: string): GitHubInfo | null;
+/**
+ * Check if a URL is a GitHub URL.
+ */
+export declare function isGitHubUrl(url: string): boolean;
+/**
+ * Sanitize a Git ref name for use in filesystem paths.
+ * Converts slashes and other problematic characters to hyphens.
+ *
+ * Examples:
+ * - main → main
+ * - feature/new-thing → feature-new-thing
+ * - v1.0.0 → v1.0.0
+ */
+export declare function sanitizeRefName(ref: string): string;
+//# sourceMappingURL=git-url-parser.d.ts.map

package/packages/core/dist/utils/git-url-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-url-parser.d.ts","sourceRoot":"","sources":["../../src/utils/git-url-parser.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,KAAK,GAAG,KAAK,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuBnD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CA6CrD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAgBhE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD"}