feat: implement Builder API for creating tar archives (#90)

* Initial plan

* Initial analysis and plan for Builder API implementation

Co-authored-by: Brooooooklyn <[email protected]>

* Implement Builder API with comprehensive tests

Co-authored-by: Brooooooklyn <[email protected]>

* Clean up test artifacts and update gitignore

Co-authored-by: Brooooooklyn <[email protected]>

* Run cargo fmt and skip three Builder tests on WASI

Co-authored-by: Brooooooklyn <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: Brooooooklyn <[email protected]>

Author: Copilot

.gitignore

@@ -131,3 +131,9 @@ Cargo.lock
 x86_64-unknown-linux-gnu
 *.wasm
 /npm
+
+# Test output files
+__test__/*.tar
+__test__/test-*
+__test__/temp*
+__test__/mixed-*

README.md

@@ -8,6 +8,8 @@
 
 ## Usage
 
+### Reading Archives
+
 ```ts
 export class Entries {
   [Symbol.iterator](): Iterator<Entry, void, void>
@@ -35,6 +37,43 @@ export class Archive {
 }
 ```
 
+### Creating Archives
+
+```ts
+export class Builder {
+  /** Create a new builder which will write to the specified output. */
+  constructor(output?: string)
+  /** Append a file from disk to this archive. */
+  appendFile(name: string, src: string): void
+  /** Append a directory and all of its contents to this archive. */
+  appendDirAll(name: string, src: string): void
+  /** Append raw data to this archive with the specified name. */
+  appendData(name: string, data: Uint8Array): void
+  /** Finalize the archive and return the resulting data. */
+  finish(): Array<number> | null
+}
+```
+
+### Creating Archives Example
+
+```ts
+import { Builder } from '@napi-rs/tar'
+
+// Create archive in memory
+const builder = new Builder()
+builder.appendData('hello.txt', Buffer.from('Hello, world!'))
+builder.appendFile('package.json', './package.json')
+builder.appendDirAll('src', './src')
+
+const archiveData = builder.finish() // Returns Uint8Array
+// archiveData can be written to disk or used directly
+
+// Create archive to file
+const fileBuilder = new Builder('./output.tar')
+fileBuilder.appendData('readme.txt', Buffer.from('Archive contents'))
+fileBuilder.finish() // Returns null, data written to ./output.tar
+```
+
 ## Extract Single File
 
 You can extract a specific file from a tar archive without extracting the entire archive. This is useful for inspecting Docker OCI images or extracting specific configuration files: