Single-file copy to trailing-separator destinations

Build a utility that copies a single file into a destination path that should be treated as a directory whenever the path ends with a trailing separator. Use the dependency for the filesystem operations rather than reimplementing copy logic.

Capabilities

Copy to directory-style destination

• When the destination ends with a path separator and the directory does not yet exist, create the directory tree and place the copied file inside using the source basename; file content must match the source. @test
• When the destination ends with a path separator pointing at an existing directory, copy the file into that directory preserving the source basename and file mode. @test

Reject conflicting file target

• If the destination ends with a path separator but resolves to an existing file, throw an error indicating the destination must be a directory. @test

Overwrite control

• If the destination file already exists and overwrite is false or omitted, fail with a clear "already exists" style error and leave the existing file unchanged. @test
• If the destination file exists and overwrite is true, replace the file and return the destination path list reflecting the new copy. @test

Implementation

@generates

API

export async function copySingleFile(
  sourcePath: string,
  destinationPath: string,
  options?: {
    overwrite?: boolean;
    verify?: boolean;
  }
): Promise<string[]>;

sourcePath is the path to an existing file to copy. destinationPath may end with a trailing path separator; when it does, treat it as a directory target (even if the directory does not exist yet) and append the source basename for the final destination file. When the destination path lacks a trailing separator, treat it as the full file target. options.overwrite controls whether existing destination files may be replaced. options.verify triggers a post-copy check that all expected destinations exist. On success, return a sorted list of destination paths written; throw errors when copy steps fail, including any aggregated filesystem errors surfaced by the dependency.

Dependencies { .dependencies }

cpr { .dependency }

Performs filesystem copy with directory creation, trailing-separator handling, overwrite control, and optional post-copy verification.