opkg 0.9.0 → 0.9.2

package/packages/core/dist/core/flows/switch-resolver.js

@@ -0,0 +1,205 @@
+/**
+ * Switch Expression Resolver
+ *
+ * Resolves $switch expressions in flow configurations to concrete target paths.
+ * Inspired by MongoDB's $switch aggregation operator.
+ */
+import { minimatch } from 'minimatch';
+import { smartEquals } from '../../utils/path-comparison.js';
+/**
+ * Extract pattern string from a SwitchCaseValue
+ */
+function extractPattern(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    return value.pattern;
+}
+/**
+ * Extract schema from a SwitchCaseValue (if present)
+ */
+function extractSchema(value) {
+    if (typeof value === 'string') {
+        return undefined;
+    }
+    return value.schema;
+}
+/**
+ * Resolve a switch expression to a concrete target path
+ *
+ * Evaluates cases in order and returns the value of the first matching case.
+ * If no cases match and a default is provided, returns the default.
+ * If no cases match and no default exists, throws an error.
+ *
+ * @param switchExpr - The switch expression to resolve
+ * @param context - Flow execution context with variables
+ * @returns Resolved target path string (for backward compatibility)
+ * @throws Error if no cases match and no default is provided
+ */
+export function resolveSwitchExpression(switchExpr, context) {
+    return resolveSwitchExpressionFull(switchExpr, context).pattern;
+}
+/**
+ * Resolve a switch expression to a full result with pattern and optional schema
+ *
+ * @param switchExpr - The switch expression to resolve
+ * @param context - Flow execution context with variables
+ * @returns Full resolution result with pattern and optional schema
+ * @throws Error if no cases match and no default is provided
+ */
+export function resolveSwitchExpressionFull(switchExpr, context) {
+    const { field, cases, default: defaultValue } = switchExpr.$switch;
+    // Resolve the field value from context variables
+    const fieldValue = resolveFieldValue(field, context);
+    // Evaluate cases in order (first match wins)
+    for (const switchCase of cases) {
+        if (matchesPattern(fieldValue, switchCase.pattern)) {
+            return {
+                pattern: extractPattern(switchCase.value),
+                schema: extractSchema(switchCase.value),
+            };
+        }
+    }
+    // No match - return default or throw error
+    if (defaultValue !== undefined) {
+        return {
+            pattern: extractPattern(defaultValue),
+            schema: extractSchema(defaultValue),
+        };
+    }
+    throw new Error(`No matching case in $switch expression for ${field}=${JSON.stringify(fieldValue)}, and no default provided`);
+}
+/**
+ * Resolve a field value from context variables
+ * Handles $$variable references
+ */
+function resolveFieldValue(field, context) {
+    if (field.startsWith('$$')) {
+        const varName = field.slice(2);
+        if (!(varName in context.variables)) {
+            throw new Error(`Variable '${varName}' not found in flow context`);
+        }
+        return context.variables[varName];
+    }
+    // Direct value (not a variable reference)
+    return field;
+}
+/**
+ * Check if a value matches a pattern
+ *
+ * Supports:
+ * - String equality (using smartEquals for path normalization)
+ * - Glob patterns (*, **, etc.)
+ * - Object deep equality
+ */
+function matchesPattern(value, pattern) {
+    // Object pattern - deep equality check
+    if (typeof pattern === 'object' && pattern !== null) {
+        return deepEquals(value, pattern);
+    }
+    // String pattern
+    if (typeof pattern === 'string') {
+        // If pattern contains glob characters, use minimatch
+        if (pattern.includes('*') || pattern.includes('?') || pattern.includes('[')) {
+            return minimatch(String(value), pattern);
+        }
+        // Exact match using smart comparison (handles ~/ normalization)
+        return smartEquals(value, pattern);
+    }
+    // Fallback to strict equality
+    return value === pattern;
+}
+/**
+ * Deep equality check for objects
+ */
+function deepEquals(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (typeof a !== 'object')
+        return a === b;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEquals(item, b[index]));
+    }
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every(key => keysB.includes(key) && deepEquals(a[key], b[key]));
+}
+/**
+ * Validate a switch expression
+ * Returns validation result with error messages
+ */
+export function validateSwitchExpression(switchExpr) {
+    const errors = [];
+    if (!switchExpr.$switch) {
+        errors.push('Switch expression must have $switch property');
+        return { valid: false, errors };
+    }
+    const { field, cases, default: defaultValue } = switchExpr.$switch;
+    // Validate field
+    if (!field) {
+        errors.push('Switch expression missing required field: field');
+    }
+    else if (typeof field !== 'string') {
+        errors.push('Switch expression field must be a string');
+    }
+    // Validate cases
+    if (!cases) {
+        errors.push('Switch expression missing required field: cases');
+    }
+    else if (!Array.isArray(cases)) {
+        errors.push('Switch expression cases must be an array');
+    }
+    else if (cases.length === 0) {
+        errors.push('Switch expression must have at least one case');
+    }
+    else {
+        // Validate each case
+        cases.forEach((switchCase, index) => {
+            if (!switchCase || typeof switchCase !== 'object') {
+                errors.push(`Case at index ${index} must be an object`);
+                return;
+            }
+            if (!('pattern' in switchCase)) {
+                errors.push(`Case at index ${index} missing required field: pattern`);
+            }
+            if (!('value' in switchCase)) {
+                errors.push(`Case at index ${index} missing required field: value`);
+            }
+            else if (!isValidSwitchCaseValue(switchCase.value)) {
+                errors.push(`Case at index ${index} value must be a string or object with 'pattern' field`);
+            }
+        });
+    }
+    // Validate default (optional, but must be valid SwitchCaseValue if provided)
+    if (defaultValue !== undefined && !isValidSwitchCaseValue(defaultValue)) {
+        errors.push('Switch expression default must be a string or object with \'pattern\' field');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Check if a value is a valid SwitchCaseValue (string or FlowPattern with pattern field)
+ */
+function isValidSwitchCaseValue(value) {
+    if (typeof value === 'string') {
+        return true;
+    }
+    if (typeof value === 'object' && value !== null && 'pattern' in value) {
+        const pattern = value.pattern;
+        return typeof pattern === 'string';
+    }
+    return false;
+}
+//# sourceMappingURL=switch-resolver.js.map

package/packages/core/dist/core/flows/switch-resolver.js.map

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

package/packages/core/dist/core/git-clone-registry.d.ts

@@ -0,0 +1,19 @@
+export interface GitCloneRegistryOptions {
+    url: string;
+    ref?: string;
+}
+export interface GitCloneRegistryResult {
+    absolutePath: string;
+    declaredPath: string;
+    user: string;
+    repo: string;
+    refOrHead: string;
+}
+/**
+ * Clone or update a git source into the local registry under:
+ *   ~/.openpackage/registry/git/<user>/<repo>/<refOrHead>/
+ *
+ * Returns the absolute path and a tilde-preserved declared path.
+ */
+export declare function cloneGitToRegistry(options: GitCloneRegistryOptions): Promise<GitCloneRegistryResult>;
+//# sourceMappingURL=git-clone-registry.d.ts.map

package/packages/core/dist/core/git-clone-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-clone-registry.d.ts","sourceRoot":"","sources":["../../src/core/git-clone-registry.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAkDD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAyCjC"}

package/packages/core/dist/core/git-clone-registry.js

@@ -0,0 +1,88 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import { getRegistryDirectories } from './directory.js';
+import { ensureDir, exists } from '../utils/fs.js';
+import { FILE_PATTERNS, GIT, REGISTRY_PATH_PREFIXES } from '../constants/index.js';
+import { logger } from '../utils/logger.js';
+const execFileAsync = promisify(execFile);
+function parseGitUrl(url) {
+    // Supports HTTPS and SSH forms for GitHub-like URLs.
+    // Examples:
+    //   https://github.com/user/repo.git
+    //   git@github.com:user/repo.git
+    const httpsMatch = url.match(/^https?:\/\/[^/]+\/([^/]+)\/([^/]+?)(\.git)?$/);
+    if (httpsMatch) {
+        return { user: httpsMatch[1], repo: httpsMatch[2] };
+    }
+    const sshMatch = url.match(/^git@[^:]+:([^/]+)\/([^/]+?)(\.git)?$/);
+    if (sshMatch) {
+        return { user: sshMatch[1], repo: sshMatch[2] };
+    }
+    throw new Error(`Unsupported git URL format: ${url}`);
+}
+function sanitizeRef(ref) {
+    if (!ref || ref.trim().length === 0)
+        return GIT.DEFAULT_REF;
+    return ref.replace(/[\\/]+/g, '_');
+}
+async function runGit(args, cwd) {
+    const meta = { args, cwd };
+    logger.debug('Running git', meta);
+    try {
+        await execFileAsync('git', args, { cwd });
+    }
+    catch (error) {
+        const message = error?.stderr?.toString?.().trim?.() || error?.message || String(error);
+        throw new Error(`Git command failed (${args.join(' ')}): ${message}`);
+    }
+}
+async function ensureOpenPackageManifestExists(dir) {
+    const manifestPath = path.join(dir, FILE_PATTERNS.OPENPACKAGE_YML);
+    if (!(await exists(manifestPath))) {
+        throw new Error(`Cloned repository at ${dir} is not an OpenPackage (missing ${FILE_PATTERNS.OPENPACKAGE_YML})`);
+    }
+}
+/**
+ * Clone or update a git source into the local registry under:
+ *   ~/.openpackage/registry/git/<user>/<repo>/<refOrHead>/
+ *
+ * Returns the absolute path and a tilde-preserved declared path.
+ */
+export async function cloneGitToRegistry(options) {
+    const { url, ref } = options;
+    const { user, repo } = parseGitUrl(url);
+    const refOrHead = sanitizeRef(ref);
+    const { packages: registryRoot } = getRegistryDirectories();
+    const targetDir = path.join(registryRoot, GIT.DIRECTORY, user, repo, refOrHead);
+    await ensureDir(path.dirname(targetDir));
+    const targetExists = await exists(targetDir);
+    if (!targetExists) {
+        const cloneArgs = [GIT.COMMANDS.CLONE, GIT.COMMANDS.DEPTH_FLAG, GIT.COMMANDS.DEPTH_VALUE];
+        if (ref) {
+            cloneArgs.push(GIT.COMMANDS.BRANCH_FLAG, ref);
+        }
+        cloneArgs.push(url, targetDir);
+        await runGit(cloneArgs);
+    }
+    else {
+        // Refresh existing clone
+        if (ref) {
+            await runGit([GIT.COMMANDS.FETCH, GIT.COMMANDS.DEPTH_FLAG, GIT.COMMANDS.DEPTH_VALUE, GIT.COMMANDS.ORIGIN, ref], targetDir);
+            await runGit([GIT.COMMANDS.CHECKOUT, ref], targetDir);
+        }
+        else {
+            await runGit([GIT.COMMANDS.PULL], targetDir);
+        }
+    }
+    await ensureOpenPackageManifestExists(targetDir);
+    const declaredPath = `${REGISTRY_PATH_PREFIXES.GIT}${user}/${repo}/${refOrHead}/`;
+    return {
+        absolutePath: path.join(targetDir, path.sep),
+        declaredPath,
+        user,
+        repo,
+        refOrHead
+    };
+}
+//# sourceMappingURL=git-clone-registry.js.map

package/packages/core/dist/core/git-clone-registry.js.map

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

package/packages/core/dist/core/git-clone.d.ts

@@ -0,0 +1,27 @@
+export interface GitCloneOptions {
+    url: string;
+    ref?: string;
+    subdir?: string;
+    skipCache?: boolean;
+}
+export interface GitCloneResult {
+    path: string;
+    commitSha: string;
+    repoPath: string;
+}
+/**
+ * Clone a Git repository to the structured cache.
+ * Uses shallow clones (--depth 1) for space efficiency.
+ *
+ * Cache structure:
+ * ~/.openpackage/cache/git/<url-hash>/<commit-sha-7>/
+ *
+ * Returns the path to the cloned repository (or subdir if specified).
+ */
+export declare function cloneRepoToCache(options: GitCloneOptions): Promise<GitCloneResult>;
+/**
+ * Legacy alias for backward compatibility.
+ * @deprecated Use cloneRepoToCache instead.
+ */
+export declare function cloneRepoToTempDir(options: GitCloneOptions): Promise<string>;
+//# sourceMappingURL=git-clone.d.ts.map

package/packages/core/dist/core/git-clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-clone.d.ts","sourceRoot":"","sources":["../../src/core/git-clone.ts"],"names":[],"mappings":"AAsCA,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0DD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAkOxF;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAGlF"}

package/packages/core/dist/core/git-clone.js

@@ -0,0 +1,282 @@
+import { execFile } from 'child_process';
+import { join } from 'path';
+import { promisify } from 'util';
+import { rm, rename } from 'fs/promises';
+import { logger } from '../utils/logger.js';
+import { ValidationError } from '../utils/errors.js';
+import { exists, ensureDir } from '../utils/fs.js';
+import { DIR_PATTERNS, FILE_PATTERNS } from '../constants/index.js';
+/**
+ * Lightweight spinner for git operations.
+ * Core package cannot depend on terminal-specific Spinner from CLI.
+ * Uses simple console.log for progress indication.
+ */
+class GitSpinner {
+    constructor(message) { this.message = message; }
+    start() { logger.debug(this.message); }
+    update(text) { this.message = text; logger.debug(text); }
+    stop() { }
+}
+import { getGitCommitCacheDir, getGitRepoCacheDir, writeRepoMetadata, writeCommitMetadata, touchCacheEntry, isCommitCached } from '../utils/git-cache.js';
+import { createCacheManager } from './cache-manager.js';
+const execFileAsync = promisify(execFile);
+const cacheManager = createCacheManager();
+function isSha(ref) {
+    return /^[0-9a-f]{7,40}$/i.test(ref);
+}
+function isFullSha(ref) {
+    return /^[0-9a-f]{40}$/i.test(ref);
+}
+async function runGit(args, cwd) {
+    try {
+        const result = await execFileAsync('git', args, { cwd });
+        return result.stdout.trim();
+    }
+    catch (error) {
+        const message = error?.stderr?.toString?.().trim?.() || error?.message || String(error);
+        throw new ValidationError(`Git command failed: ${message}`);
+    }
+}
+/**
+ * Get the current commit SHA of a Git repository.
+ */
+async function getCurrentCommitSha(repoPath) {
+    const fullSha = await runGit(['rev-parse', 'HEAD'], repoPath);
+    return fullSha.substring(0, 7);
+}
+/**
+ * Resolve a ref to a commit SHA using ls-remote (without cloning).
+ * Returns the 7-char short SHA or null if resolution fails.
+ *
+ * When ref is undefined or 'HEAD', resolves the default branch.
+ */
+async function resolveRefWithLsRemote(url, ref) {
+    try {
+        const targetRef = ref || 'HEAD';
+        const output = await runGit(['ls-remote', url, targetRef]);
+        if (!output) {
+            return null;
+        }
+        const match = output.match(/^([0-9a-f]{40})\s/i);
+        return match ? match[1].substring(0, 7) : null;
+    }
+    catch {
+        return null;
+    }
+}
+const SEMVER_TAG_PATTERN = /^v?\d+\.\d+\.\d+(?:[-+].*)?$/;
+/**
+ * Check if a ref is immutable (full SHA or semver tag).
+ * Immutable refs never change, so we can trust cached mappings forever.
+ */
+function isImmutableRef(ref) {
+    return isFullSha(ref) || SEMVER_TAG_PATTERN.test(ref);
+}
+/**
+ * Clone a Git repository to the structured cache.
+ * Uses shallow clones (--depth 1) for space efficiency.
+ *
+ * Cache structure:
+ * ~/.openpackage/cache/git/<url-hash>/<commit-sha-7>/
+ *
+ * Returns the path to the cloned repository (or subdir if specified).
+ */
+export async function cloneRepoToCache(options) {
+    const { url, ref, subdir, skipCache } = options;
+    // Format URL for display (extract repo name from URL)
+    const getDisplayUrl = () => {
+        const match = url.match(/([^/]+\/[^/]+?)(?:\.git)?$/);
+        return match ? match[1] : url;
+    };
+    // Helper to check cache and return result if hit
+    const tryCache = async (shortSha, source) => {
+        if (await isCommitCached(url, shortSha)) {
+            const commitDir = getGitCommitCacheDir(url, shortSha);
+            await touchCacheEntry(commitDir);
+            const finalPath = subdir ? join(commitDir, subdir) : commitDir;
+            if (!subdir || await exists(finalPath)) {
+                logger.debug(`Using cached commit (${source})`, { url, ref, commit: shortSha });
+                // Show cache hit to user via OutputPort
+                const refDisplay = ref ? `#${ref}` : '';
+                const subdirDisplay = subdir ? `/${subdir}` : '';
+                logger.info(`Using cached ${getDisplayUrl()}${refDisplay}${subdirDisplay} [${shortSha}]`);
+                return { path: finalPath, commitSha: shortSha, repoPath: commitDir };
+            }
+        }
+        return null;
+    };
+    // CACHE CHECK: Skip if skipCache is set (--remote flag forces fresh fetch)
+    if (!skipCache) {
+        // Case 1: Full SHA provided - check cache directly (no network needed)
+        if (ref && isFullSha(ref)) {
+            const shortSha = ref.substring(0, 7);
+            const cached = await tryCache(shortSha, 'full SHA');
+            if (cached)
+                return cached;
+        }
+        // Case 2: Immutable ref (semver tag) - trust ref cache without TTL
+        if (ref && isImmutableRef(ref) && !isFullSha(ref)) {
+            const cachedCommit = await cacheManager.getCachedCommitForRef(url, ref);
+            if (cachedCommit) {
+                const cached = await tryCache(cachedCommit, 'immutable ref cache');
+                if (cached)
+                    return cached;
+            }
+        }
+        // Case 3: Mutable ref (branch) or no ref (default branch)
+        // Always do ls-remote to get current SHA, then check cache
+        // This is the key fix: we now handle ref === undefined
+        const refDisplay = ref ? `#${ref}` : '';
+        const spinner = new GitSpinner(`Checking ${getDisplayUrl()}${refDisplay}`);
+        spinner.start();
+        const resolvedSha = await resolveRefWithLsRemote(url, ref);
+        spinner.stop();
+        if (resolvedSha) {
+            // Update ref cache for future lookups
+            if (ref) {
+                await cacheManager.cacheRefCommit(url, ref, resolvedSha);
+            }
+            const cached = await tryCache(resolvedSha, 'ls-remote');
+            if (cached)
+                return cached;
+            // SHA resolved but not cached - will need to clone
+            logger.debug('Commit not cached, will clone', { url, ref, resolvedSha });
+        }
+    }
+    // Clone to a temporary commit directory (we'll get the actual SHA after cloning)
+    const repoDir = getGitRepoCacheDir(url);
+    await ensureDir(repoDir);
+    // Write repo metadata
+    await writeRepoMetadata(repoDir, {
+        url,
+        normalized: url.toLowerCase(),
+        lastFetched: new Date().toISOString()
+    });
+    // Create a unique temporary clone location.
+    // IMPORTANT: recursive dependency resolution may clone multiple resources from the same repo in parallel.
+    // A fixed temp dir causes collisions ("File exists") and leaves partial clones behind.
+    const tempClonePath = join(repoDir, `.temp-clone-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`);
+    logger.debug(`Cloning repository to cache`, { url, ref, subdir });
+    // Create spinner for git operations
+    const refDisplay = ref ? `#${ref}` : '';
+    const spinner = new GitSpinner(`Cloning repository from ${url}${refDisplay}`);
+    spinner.start();
+    try {
+        // Clone repository
+        if (ref && isSha(ref)) {
+            // SHA: shallow clone default branch, then fetch the sha
+            await runGit(['clone', '--depth', '1', url, tempClonePath]);
+            spinner.update(`Fetching commit ${ref}`);
+            await runGit(['fetch', '--depth', '1', 'origin', ref], tempClonePath);
+            spinner.update(`Checking out commit ${ref}`);
+            await runGit(['checkout', ref], tempClonePath);
+        }
+        else if (ref) {
+            // Branch or tag
+            await runGit(['clone', '--depth', '1', '--branch', ref, url, tempClonePath]);
+        }
+        else {
+            // Default branch
+            await runGit(['clone', '--depth', '1', url, tempClonePath]);
+        }
+        // Get the actual commit SHA
+        spinner.update('Resolving commit SHA');
+        const commitSha = await getCurrentCommitSha(tempClonePath);
+        const commitDir = getGitCommitCacheDir(url, commitSha);
+        // Check if this commit is already cached
+        if (await isCommitCached(url, commitSha)) {
+            logger.debug(`Commit already cached, using existing`, { commitSha, commitDir });
+            spinner.stop();
+            // Clean up temp clone
+            await rm(tempClonePath, { recursive: true, force: true });
+            // Update access time
+            await touchCacheEntry(commitDir);
+            // Validate subdir if specified
+            const finalPath = subdir ? join(commitDir, subdir) : commitDir;
+            if (subdir && !(await exists(finalPath))) {
+                throw new ValidationError(`Subdirectory '${subdir}' does not exist in cached repository ${url}`);
+            }
+            return {
+                path: finalPath,
+                commitSha,
+                repoPath: commitDir
+            };
+        }
+        // Move temp clone to final location.
+        // If another parallel clone won the race and created the commitDir, fall back to using the cached copy.
+        try {
+            await rename(tempClonePath, commitDir);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'EEXIST' || code === 'ENOTEMPTY') {
+                // Another process wrote this commit in parallel.
+                await rm(tempClonePath, { recursive: true, force: true });
+            }
+            else {
+                throw error;
+            }
+        }
+        logger.debug(`Moved clone to final cache location`, { commitDir });
+        // If a parallel clone created commitDir, ensure we treat it as cached from here on.
+        if (await isCommitCached(url, commitSha)) {
+            await touchCacheEntry(commitDir);
+        }
+        // Write commit metadata
+        await writeCommitMetadata(commitDir, {
+            url,
+            commit: commitSha,
+            ref,
+            subdir,
+            clonedAt: new Date().toISOString(),
+            lastAccessed: new Date().toISOString()
+        });
+        // Cache the ref->commit mapping for future lookups
+        if (ref) {
+            await cacheManager.cacheRefCommit(url, ref, commitSha);
+        }
+        // Validate subdir if specified
+        const finalPath = subdir ? join(commitDir, subdir) : commitDir;
+        if (subdir && !(await exists(finalPath))) {
+            throw new ValidationError(`Subdirectory '${subdir}' does not exist in cloned repository ${url}`);
+        }
+        // Validate that it's an OpenPackage or Claude Code plugin
+        const manifestPath = join(finalPath, FILE_PATTERNS.OPENPACKAGE_YML);
+        const hasManifest = await exists(manifestPath);
+        const pluginManifestPath = join(finalPath, DIR_PATTERNS.CLAUDE_PLUGIN, FILE_PATTERNS.PLUGIN_JSON);
+        const hasPluginManifest = await exists(pluginManifestPath);
+        const marketplaceManifestPath = join(finalPath, DIR_PATTERNS.CLAUDE_PLUGIN, FILE_PATTERNS.MARKETPLACE_JSON);
+        const hasMarketplaceManifest = await exists(marketplaceManifestPath);
+        if (!hasManifest && !hasPluginManifest && !hasMarketplaceManifest) {
+            throw new ValidationError(`Cloned repository is not an OpenPackage or Claude Code plugin ` +
+                `(missing ${FILE_PATTERNS.OPENPACKAGE_YML}, ${DIR_PATTERNS.CLAUDE_PLUGIN}/${FILE_PATTERNS.PLUGIN_JSON}, or ${DIR_PATTERNS.CLAUDE_PLUGIN}/${FILE_PATTERNS.MARKETPLACE_JSON} ` +
+                `at ${subdir ? `subdir '${subdir}'` : 'repository root'})`);
+        }
+        spinner.stop();
+        const refPart = ref ? `#${ref}` : '';
+        const subdirPart = subdir ? `&subdirectory=${subdir}` : '';
+        logger.info(`Cloned git repository ${url}${refPart}${subdirPart} to cache [${commitSha}]`);
+        return {
+            path: finalPath,
+            commitSha,
+            repoPath: commitDir
+        };
+    }
+    catch (error) {
+        spinner.stop();
+        // Clean up temp clone on error
+        if (await exists(tempClonePath)) {
+            await rm(tempClonePath, { recursive: true, force: true });
+        }
+        throw error;
+    }
+}
+/**
+ * Legacy alias for backward compatibility.
+ * @deprecated Use cloneRepoToCache instead.
+ */
+export async function cloneRepoToTempDir(options) {
+    const result = await cloneRepoToCache(options);
+    return result.path;
+}
+//# sourceMappingURL=git-clone.js.map