🚀 [Feature]: YAML files can be imported and exported directly

[Marius Storhaug (MariusStorhaug)]

YAML configuration can now be read from and written to files directly with strict Unicode handling, deterministic multi-file imports, and failure-safe atomic exports.

New: Read YAML files directly

Import-Yaml reads any file extension, expands wildcard -Path values, accepts pipeline file objects, and treats -LiteralPath values exactly. Files are deduplicated and processed in deterministic path order while documents retain their order within each file.

$config = Import-Yaml -Path '.\config\*.yaml' -AsHashtable

UTF-8 without a byte order mark is the default. UTF-8, UTF-16, and UTF-32 byte order marks are detected automatically, malformed bytes terminate with a path-specific error, and parser projection and resource-limit controls match direct YAML conversion.

New: Write YAML files safely

Export-Yaml aggregates pipeline records into one YAML value and writes UTF-8 with LF and one final newline by default. Encoding, line endings, final-newline policy, serializer limits, directory creation, overwrite behavior, and pass-through output are configurable.

$config | Export-Yaml -Path '.\config.yaml'

Serialization and encoding finish before filesystem mutation. Approved writes use a cryptographically random same-directory temporary file and atomic publication; -WhatIf creates nothing, -NoClobber prevents replacement, and -Force permits read-only replacement while restoring the read-only state.

Technical Details

• File commands delegate YAML parsing and serialization to ConvertFrom-Yaml and ConvertTo-Yaml rather than duplicating engine logic.
• Import identity keys are component-aware, normalization-aware, and deterministic across case-sensitive, case-insensitive, and Windows per-directory case-sensitive filesystems.
• Pipeline strings bind by value to wildcard-aware Path, while FileInfo, PSPath, and FullName pipeline properties bind exclusively to literal path resolution so wildcard characters in filenames are never expanded accidentally.
• Export preserves each single pipeline record exactly, including explicit empty and one-element arrays; multiple records form a sequence just like ConvertTo-Yaml.
• Export flushes strict encoded bytes before atomic move or replacement, preserves Windows replacement metadata and Unix mode bits, restores native replacement failures from a separately randomized backup, and cleans temporary artifacts in finally.
• Process-PSModule v6.1.13 run 30142371937 passed source and built-module tests and lint on Windows, Linux, and macOS, generated command documentation, and built the Zensical site. The downloaded artifact passed 276 local tests with 0 failures and exports the five intended commands.
• Implementation plan progress: all file import, atomic export, packaging, documentation, and cross-platform validation tasks in Add Import-Yaml and Export-Yaml file I/O functions #29 are complete; Format, Merge, and Remove remain outside this work item.

Related issues

• Fixes Add Import-Yaml and Export-Yaml file I/O functions #29

[Marius Storhaug (MariusStorhaug)]

Superseded by #47 (release/v1.0.0 consolidation PR). Closing this stacked layer as part of release cleanup.