opkg 0.9.0 → 0.9.2

package/packages/core/dist/core/save/save-to-source-pipeline.js

@@ -0,0 +1,234 @@
+/**
+ * Save To Source Pipeline
+ *
+ * This module orchestrates the complete save operation, integrating all phases:
+ * - Phase 1: Validation
+ * - Phase 2: Candidate Discovery & Grouping
+ * - Phase 3: Platform Pruning & Filtering
+ * - Phase 4: Conflict Analysis & Resolution
+ * - Phase 5: File Writes
+ * - Phase 6: Result Reporting
+ *
+ * This is the main entry point for the enhanced save command.
+ *
+ * @module save-to-source-pipeline
+ */
+import { assertMutableSourceOrThrow } from '../source-mutability.js';
+import { readWorkspaceIndex } from '../../utils/workspace-index-yml.js';
+import { resolvePackageSource } from '../source-resolution/resolve-package-source.js';
+import { logger } from '../../utils/logger.js';
+import { resolveOutput, resolvePrompt } from '../ports/resolve.js';
+import { buildCandidates, materializeLocalCandidate } from './save-candidate-builder.js';
+import { buildCandidateGroups, filterGroupsWithWorkspace } from './save-group-builder.js';
+import { analyzeGroup } from './save-conflict-analyzer.js';
+import { executeResolution } from './save-resolution-executor.js';
+import { pruneExistingPlatformCandidates } from './save-platform-handler.js';
+import { writeResolution } from './save-write-coordinator.js';
+import { clearConversionCache, initSharedTempDir, cleanupSharedTempDir } from './save-conversion-helper.js';
+import { buildSaveReport, createCommandResult, createSuccessResult, createErrorResult } from './save-result-reporter.js';
+/**
+ * Run the complete save-to-source pipeline
+ *
+ * This is the main orchestrator function that coordinates all phases
+ * of the save operation:
+ *
+ * 1. **Validate preconditions**: Check package exists, is mutable, has files
+ * 2. **Build candidates**: Discover files in workspace and source
+ * 3. **Group candidates**: Organize by registry path
+ * 4. **Prune platform candidates**: Remove candidates with existing platform files
+ * 5. **Filter active groups**: Keep only groups with workspace changes
+ * 6. **Analyze & resolve**: Classify conflicts and execute resolution strategies
+ * 7. **Write files**: Execute file write operations
+ * 8. **Report results**: Build and return comprehensive report
+ *
+ * @param packageName - Package name to save
+ * @param options - Save options (force mode, etc.)
+ * @returns CommandResult with success status and report data
+ */
+export async function runSaveToSourcePipeline(packageName, options = {}, ctx) {
+    try {
+        await initSharedTempDir();
+        // Phase 1: Validate preconditions
+        logger.debug(`Validating save preconditions for ${packageName}`);
+        const validation = await validateSavePreconditions(packageName);
+        if (!validation.valid) {
+            return createErrorResult(validation.error);
+        }
+        const { cwd, packageRoot, filesMapping } = validation;
+        // Phase 2: Build candidates from workspace and source
+        logger.debug(`Building candidates for ${packageName}`);
+        const candidateResult = await buildCandidates({
+            packageRoot: packageRoot,
+            workspaceRoot: cwd,
+            filesMapping: filesMapping
+        });
+        if (candidateResult.errors.length > 0) {
+            logger.warn(`Encountered ${candidateResult.errors.length} error(s) building candidates`);
+            candidateResult.errors.forEach(err => logger.warn(`  ${err.path}: ${err.reason}`));
+        }
+        // Phase 3: Build candidate groups (organize by registry path)
+        logger.debug('Building candidate groups');
+        const allGroups = buildCandidateGroups(candidateResult.localSourceRefs, candidateResult.workspaceCandidates, cwd);
+        // Phase 4: Filter first (cheap), then prune only active groups
+        const activeGroups = filterGroupsWithWorkspace(allGroups);
+        if (activeGroups.length === 0) {
+            logger.info(`No workspace changes detected for ${packageName}`);
+            return createSuccessResult(packageName, `✓ Saved ${packageName}\n  No workspace changes detected`);
+        }
+        // Prune only active groups (instead of all groups)
+        logger.debug('Pruning existing platform-specific files');
+        await pruneExistingPlatformCandidates(packageRoot, activeGroups);
+        // Re-filter after pruning (pruning may have removed all workspace candidates from some groups)
+        const finalGroups = activeGroups.filter(g => g.workspace.length > 0);
+        if (finalGroups.length === 0) {
+            logger.info(`No workspace changes detected for ${packageName}`);
+            return createSuccessResult(packageName, `✓ Saved ${packageName}\n  No workspace changes detected`);
+        }
+        // Phase 5: Materialize local candidates on demand for active groups
+        for (const group of finalGroups) {
+            if (group.localRef && !group.local) {
+                group.local = await materializeLocalCandidate(group.localRef, packageRoot) ?? undefined;
+            }
+        }
+        logger.debug(`Processing ${finalGroups.length} group(s) with workspace candidates`);
+        // Phase 6: Analyze all groups first, then split into auto-resolvable vs interactive
+        const groupAnalyses = await Promise.all(finalGroups.map(async (group) => ({
+            group,
+            analysis: await analyzeGroup(group, options.force ?? false, cwd)
+        })));
+        const analyses = groupAnalyses.map(ga => ga.analysis);
+        const allWriteResults = [];
+        // Partition: auto-resolvable groups can run in parallel, interactive must be serial
+        const autoResolvable = [];
+        const interactive = [];
+        for (const ga of groupAnalyses) {
+            if (ga.analysis.type === 'no-action-needed' || ga.analysis.type === 'no-change-needed') {
+                logger.debug(`Skipping ${ga.group.registryPath}: ${ga.analysis.type}`);
+                continue;
+            }
+            if (ga.analysis.recommendedStrategy === 'interactive') {
+                interactive.push(ga);
+            }
+            else {
+                autoResolvable.push(ga);
+            }
+        }
+        // Process auto-resolvable groups in parallel
+        if (autoResolvable.length > 0) {
+            logger.debug(`Processing ${autoResolvable.length} auto-resolvable group(s) in parallel`);
+            const autoResults = await Promise.all(autoResolvable.map(async ({ group, analysis }) => {
+                const resolution = await executeResolution(group, analysis, packageRoot, cwd, resolveOutput(ctx), resolvePrompt(ctx));
+                if (!resolution)
+                    return null;
+                return writeResolution(packageRoot, group.registryPath, resolution, group.local, cwd);
+            }));
+            for (const result of autoResults) {
+                if (result)
+                    allWriteResults.push(result);
+            }
+        }
+        // Process interactive groups serially (require user input)
+        for (const { group, analysis } of interactive) {
+            const resolution = await executeResolution(group, analysis, packageRoot, cwd, resolveOutput(ctx), resolvePrompt(ctx));
+            if (!resolution) {
+                logger.debug(`No resolution returned for ${group.registryPath}`);
+                continue;
+            }
+            const writeResults = await writeResolution(packageRoot, group.registryPath, resolution, group.local, cwd);
+            allWriteResults.push(writeResults);
+        }
+        // Phase 7: Build and format report
+        logger.debug('Building save report');
+        const report = buildSaveReport(packageName, analyses, allWriteResults);
+        // Phase 8: Return result
+        return createCommandResult(report);
+    }
+    finally {
+        clearConversionCache();
+        await cleanupSharedTempDir();
+    }
+}
+/**
+ * Validate save preconditions
+ *
+ * Performs comprehensive validation before attempting save operation:
+ * - Package name is provided
+ * - Workspace index exists and is readable
+ * - Package exists in index
+ * - Package has file mappings
+ * - Package source is resolvable
+ * - Source is mutable (not registry)
+ *
+ * @param packageName - Package name to validate
+ * @returns Validation result with success status and required data or error
+ */
+async function validateSavePreconditions(packageName) {
+    const cwd = process.cwd();
+    // Check package name provided
+    if (!packageName) {
+        return {
+            valid: false,
+            error: 'Package name is required for save.'
+        };
+    }
+    // Read workspace index
+    let index;
+    try {
+        const result = await readWorkspaceIndex(cwd);
+        index = result.index;
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: `Failed to read workspace index: ${error}`
+        };
+    }
+    // Check package exists in index
+    const pkgIndex = index.packages?.[packageName];
+    if (!pkgIndex) {
+        return {
+            valid: false,
+            error: `Package '${packageName}' is not installed in this workspace.\n` +
+                `Run 'opkg install ${packageName}' to install it first.`
+        };
+    }
+    // Check package has file mappings
+    if (!pkgIndex.files || Object.keys(pkgIndex.files).length === 0) {
+        return {
+            valid: false,
+            error: `Package '${packageName}' has no files installed.\n` +
+                `Nothing to save.`
+        };
+    }
+    // Resolve package source
+    let source;
+    try {
+        source = await resolvePackageSource(cwd, packageName);
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: `Failed to resolve package source: ${error}`
+        };
+    }
+    // Check source is mutable
+    try {
+        assertMutableSourceOrThrow(source.absolutePath, {
+            packageName: source.packageName,
+            command: 'save'
+        });
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+    return {
+        valid: true,
+        cwd,
+        packageRoot: source.absolutePath,
+        filesMapping: pkgIndex.files
+    };
+}
+//# sourceMappingURL=save-to-source-pipeline.js.map

package/packages/core/dist/core/save/save-to-source-pipeline.js.map

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

package/packages/core/dist/core/save/save-types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Type definitions for the enhanced save subsystem
+ *
+ * This module defines the core data structures used across all phases of the
+ * save pipeline, including candidates, groups, resolution strategies, and write operations.
+ */
+import type { Platform } from '../platforms.js';
+/**
+ * Lightweight reference to a local source file (path metadata only, no content).
+ * Used during the grouping phase to avoid reading file content eagerly.
+ */
+export interface LocalSourceRef {
+    registryPath: string;
+    fullPath: string;
+}
+/**
+ * Source type for a save candidate
+ * - 'local': File exists in package source
+ * - 'workspace': File exists in workspace
+ */
+export type SaveCandidateSource = 'local' | 'workspace';
+/**
+ * SaveCandidate represents a single file version with rich metadata
+ *
+ * A candidate can come from either the package source (local) or the workspace.
+ * Each candidate contains content, hash, timestamps, and optional platform/frontmatter data.
+ */
+export interface SaveCandidate {
+    /** Source location: 'local' (package) or 'workspace' */
+    source: SaveCandidateSource;
+    /** Normalized registry path (e.g., "tools/search.md") */
+    registryPath: string;
+    /** Absolute filesystem path */
+    fullPath: string;
+    /** File content as string */
+    content: string;
+    /** Content hash for comparison (xxhash3) */
+    contentHash: string;
+    /** Modification timestamp in milliseconds */
+    mtime: number;
+    /** User-friendly relative display path */
+    displayPath: string;
+    /** Inferred platform for workspace files ('cursor', 'claude', 'windsurf', etc.) */
+    platform?: Platform | 'ai';
+    /** Whether this is a root package file (AGENTS.md, etc.) */
+    isRootFile?: boolean;
+    /** Parsed YAML frontmatter (for markdown files) */
+    frontmatter?: any;
+    /** Raw frontmatter text (without delimiters) */
+    rawFrontmatter?: string;
+    /** Markdown body without frontmatter */
+    markdownBody?: string;
+    /** Whether the file is markdown */
+    isMarkdown?: boolean;
+    /** Merge strategy used during installation (for workspace files) */
+    mergeStrategy?: 'deep' | 'shallow' | 'replace' | 'composite';
+    /** Keys contributed by this package (for merged files) */
+    mergeKeys?: string[];
+    /** Cached comparable hash (after conversion/extraction), computed once */
+    comparableHash?: string;
+    /** Cached extracted content (for merged files), computed once */
+    extractedContent?: string;
+}
+/**
+ * SaveCandidateGroup organizes all versions of a single file by registry path
+ *
+ * A group contains:
+ * - One optional local (source) candidate
+ * - Zero or more workspace candidates (may have platform variants)
+ */
+export interface SaveCandidateGroup {
+    /** The canonical registry path for this group */
+    registryPath: string;
+    /** Optional local (source) candidate (materialized on demand) */
+    local?: SaveCandidate;
+    /** Lightweight local source reference (set during grouping, before materialization) */
+    localRef?: LocalSourceRef;
+    /** Array of workspace candidates (may be empty, single, or multiple) */
+    workspace: SaveCandidate[];
+}
+/**
+ * ResolutionStrategy defines the approach to resolve a candidate group
+ *
+ * Strategies progress from automatic to interactive based on conflict complexity:
+ * - 'skip': No workspace candidates (no action needed)
+ * - 'write-single': Single workspace candidate (auto-write)
+ * - 'write-newest': Multiple identical candidates (auto-write newest)
+ * - 'force-newest': Multiple differing candidates, force mode enabled (auto-select newest)
+ * - 'interactive': Multiple differing candidates, user prompt required
+ */
+export type ResolutionStrategy = 'skip' | 'write-single' | 'write-newest' | 'force-newest' | 'interactive';
+/**
+ * ResolutionResult captures the outcome of resolving a candidate group
+ *
+ * Contains:
+ * - The selected universal candidate (or null if only platform-specific)
+ * - Any platform-specific candidates to preserve separately
+ * - The strategy used
+ * - Whether user interaction occurred
+ */
+export interface ResolutionResult {
+    /** Chosen universal candidate (null if only platform-specific variants) */
+    selection: SaveCandidate | null;
+    /** Array of candidates marked as platform-specific */
+    platformSpecific: SaveCandidate[];
+    /** Which resolution strategy was used */
+    strategy: ResolutionStrategy;
+    /** Whether user was prompted */
+    wasInteractive: boolean;
+}
+/**
+ * WriteOperation describes a pending file write
+ *
+ * Represents an operation to be executed against the filesystem,
+ * including target path, content, and operation type.
+ */
+export interface WriteOperation {
+    /** Target registry path */
+    registryPath: string;
+    /** Absolute filesystem target path */
+    targetPath: string;
+    /** Content to write */
+    content: string;
+    /** Operation type */
+    operation: 'create' | 'update' | 'skip';
+    /** Whether this is a platform-specific file */
+    isPlatformSpecific: boolean;
+    /** Platform name if applicable */
+    platform?: string;
+}
+/**
+ * WriteResult captures the outcome of a write operation
+ *
+ * Tracks success/failure for each write with optional error details.
+ */
+export interface WriteResult {
+    /** The write operation that was executed */
+    operation: WriteOperation;
+    /** Whether the write succeeded */
+    success: boolean;
+    /** Optional error object if write failed */
+    error?: Error;
+}
+/**
+ * CandidateBuildError represents a non-fatal error during candidate building
+ *
+ * These errors are collected and reported but don't halt the pipeline.
+ */
+export interface CandidateBuildError {
+    /** Filesystem path that failed */
+    path: string;
+    /** Intended registry path */
+    registryPath: string;
+    /** Human-readable error message */
+    reason: string;
+}
+//# sourceMappingURL=save-types.d.ts.map

package/packages/core/dist/core/save/save-types.d.ts.map

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

package/packages/core/dist/core/save/save-types.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for the enhanced save subsystem
+ *
+ * This module defines the core data structures used across all phases of the
+ * save pipeline, including candidates, groups, resolution strategies, and write operations.
+ */
+export {};
+//# sourceMappingURL=save-types.js.map

package/packages/core/dist/core/save/save-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-types.js","sourceRoot":"","sources":["../../../src/core/save/save-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/packages/core/dist/core/save/save-write-coordinator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Write Coordinator
+ *
+ * This module coordinates file write operations for resolved save content.
+ * It handles both universal content and platform-specific variants,
+ * ensuring idempotent writes with optimization for unchanged files.
+ *
+ * Key responsibilities:
+ * - Build write operations from resolution results
+ * - Execute writes to filesystem
+ * - Handle directory creation
+ * - Track success/failure for each write
+ * - Optimize by skipping writes when content is identical
+ *
+ * @module save-write-coordinator
+ */
+import type { SaveCandidate, ResolutionResult, WriteResult } from './save-types.js';
+/**
+ * Write resolution results to package source
+ *
+ * This is the main entry point for file writes. It handles both:
+ * - Universal content (if selected)
+ * - Platform-specific content (for each platform candidate)
+ *
+ * Each write is tracked individually with success/failure status.
+ * Individual write failures don't halt the pipeline.
+ *
+ * @param packageRoot - Absolute path to package source
+ * @param registryPath - Registry path being written
+ * @param resolution - Resolution result from conflict resolution
+ * @param localCandidate - Optional local (source) candidate for comparison
+ * @param workspaceRoot - Optional workspace root for import transformations
+ * @returns Array of write results (one per write operation)
+ */
+export declare function writeResolution(packageRoot: string, registryPath: string, resolution: ResolutionResult, localCandidate?: SaveCandidate, workspaceRoot?: string): Promise<WriteResult[]>;
+//# sourceMappingURL=save-write-coordinator.d.ts.map

package/packages/core/dist/core/save/save-write-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-write-coordinator.d.ts","sourceRoot":"","sources":["../../../src/core/save/save-write-coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAYH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAkB,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGpG;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,gBAAgB,EAC5B,cAAc,CAAC,EAAE,aAAa,EAC9B,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,WAAW,EAAE,CAAC,CA8BxB"}