Workspace Sync Utility

Utility for copying multiple source paths into a workspace root using robust recursive copying with optional cleanup, filtering, and verification.

Capabilities

Copy manifest entries

• Given multiple manifest entries that point to existing files or directories, copies each source into its destination under targetRoot, preserving nested structure, and resolves with a sorted list of absolute destination paths returned by the dependency on success. @test

Ignore patterns

• When ignorePattern is provided, paths whose absolute locations match the pattern are excluded from copying while all other paths are copied. @test

Clean destination

• When clean is true and a destination already exists with extra files, those files are removed before copying so the final destination contents match the sources. @test

Verification

• When verify is true and any expected destination path is missing after copying, the promise rejects with an error; when every copied path exists, it resolves normally. @test

Implementation

Use the dependency's recursive copy facility for each manifest entry instead of manual filesystem traversal or shell commands.

@generates

API

export interface ManifestEntry {
  /**
   * Absolute or relative path to copy from.
   */
  source: string;
  /**
   * Destination path relative to targetRoot.
   */
  destination: string;
}

export interface SyncOptions {
  /**
   * Directory under which all destination paths are created.
   */
  targetRoot: string;
  /**
   * Regex tested against absolute source paths to exclude matching items.
   */
  ignorePattern?: RegExp;
  /**
   * Remove destination before copying when true.
   */
  clean?: boolean;
  /**
   * Re-verify that every reported destination path exists after copying.
   */
  verify?: boolean;
  /**
   * Allow overwriting when destinations already exist.
   */
  overwrite?: boolean;
}

/**
 * Copies all manifest entries into the workspace root, applying filtering, cleanup,
 * and optional verification before resolving with sorted absolute destination paths.
 */
export function syncWorkspace(manifest: ManifestEntry[], options: SyncOptions): Promise<string[]>;

Dependencies { .dependencies }

cpr { .dependency }

Provides recursive copy with filtering, overwrite control, optional cleanup, and a list of copied destination paths.