@kexi/vibe-native 0.12.5

package/README.md

@@ -0,0 +1,156 @@
+# @kexi/vibe-native
+
+Native Copy-on-Write (CoW) file cloning for Node.js using Rust (napi-rs).
+
+## Features
+
+- **macOS**: Uses `clonefile()` syscall on APFS filesystems
+- **Linux**: Uses `FICLONE` ioctl on Btrfs/XFS filesystems
+- **Zero-copy**: Creates instant file clones without copying data
+- **Async/Sync**: Both async and sync APIs available
+- **Type-safe**: Full TypeScript support with auto-generated types
+
+## Installation
+
+```bash
+npm install @kexi/vibe-native
+# or
+pnpm add @kexi/vibe-native
+```
+
+## Platform Support
+
+| Platform | Architecture | Filesystem |
+|----------|--------------|------------|
+| macOS | x64, arm64 | APFS |
+| Linux | x64, arm64 | Btrfs, XFS (with reflink) |
+
+## Usage
+
+```typescript
+import {
+  cloneAsync,
+  cloneSync,
+  isAvailable,
+  supportsDirectory,
+  getPlatform,
+} from "@kexi/vibe-native";
+
+// Check if native cloning is available
+if (isAvailable()) {
+  console.log(`Platform: ${getPlatform()}`);
+  console.log(`Directory cloning: ${supportsDirectory()}`);
+
+  // Async cloning (recommended)
+  await cloneAsync("/path/to/source", "/path/to/dest");
+
+  // Sync cloning
+  cloneSync("/path/to/source", "/path/to/dest");
+}
+```
+
+## API
+
+### `cloneAsync(src: string, dest: string): Promise<void>`
+
+Clone a file or directory asynchronously using native Copy-on-Write.
+
+### `cloneSync(src: string, dest: string): void`
+
+Clone a file or directory synchronously using native Copy-on-Write.
+
+### `clone(src: string, dest: string): void`
+
+Alias for `cloneSync` (for backward compatibility).
+
+### `isAvailable(): boolean`
+
+Check if native clone operations are available on the current platform.
+
+### `supportsDirectory(): boolean`
+
+Check if directory cloning is supported:
+- macOS (`clonefile`): `true`
+- Linux (`FICLONE`): `false` (files only)
+
+### `getPlatform(): "darwin" | "linux" | "unknown"`
+
+Get the current platform identifier.
+
+## Security
+
+### File Type Validation
+
+Only regular files and directories are allowed. The following are rejected:
+- Symlinks (to prevent path traversal)
+- Device files (block/character devices)
+- Sockets
+- FIFOs (named pipes)
+
+### Path Handling
+
+This library does not perform path normalization or validation. Callers should:
+- Validate paths before calling clone functions
+- Use `path.resolve()` to normalize relative paths
+- Check for symlinks if path traversal is a concern
+
+```typescript
+import { resolve, dirname } from "path";
+import { realpath } from "fs/promises";
+
+// Example: Safe path handling
+async function safeClone(src: string, dest: string, allowedDir: string) {
+  const resolvedSrc = await realpath(resolve(src));
+  const resolvedDest = resolve(dest);
+
+  // Verify paths are within allowed directory
+  if (!resolvedSrc.startsWith(allowedDir)) {
+    throw new Error("Source path outside allowed directory");
+  }
+  if (!resolvedDest.startsWith(allowedDir)) {
+    throw new Error("Destination path outside allowed directory");
+  }
+
+  await cloneAsync(resolvedSrc, resolvedDest);
+}
+```
+
+## Error Handling
+
+Errors include system errno information for debugging:
+
+```typescript
+try {
+  await cloneAsync("/nonexistent", "/dest");
+} catch (error) {
+  // Error: open source failed: No such file or directory (errno 2)
+  console.error(error.message);
+}
+```
+
+## Filesystem Requirements
+
+### macOS
+- **APFS** is required for `clonefile()` to work
+- HFS+ and other filesystems will return `ENOTSUP`
+
+### Linux
+- **Btrfs** or **XFS** (with reflink support) is required
+- ext4 and other filesystems will return `EOPNOTSUPP`
+
+## Building from Source
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build (requires Rust toolchain)
+pnpm run build
+
+# Run tests
+cargo test
+```
+
+## License
+
+Apache-2.0

package/index.d.ts

@@ -0,0 +1,34 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * Clone a file or directory synchronously using native Copy-on-Write
+ *
+ * - macOS: Uses clonefile() which supports both files and directories
+ * - Linux: Uses FICLONE ioctl which only supports files
+ */
+export declare function cloneSync(src: string, dest: string): void
+/**
+ * Clone a file or directory asynchronously using native Copy-on-Write
+ *
+ * - macOS: Uses clonefile() which supports both files and directories
+ * - Linux: Uses FICLONE ioctl which only supports files
+ */
+export declare function cloneAsync(src: string, dest: string): Promise<void>
+/** Clone a file or directory synchronously (alias for cloneSync for backward compatibility) */
+export declare function clone(src: string, dest: string): void
+/** Check if native clone operations are available */
+export declare function isAvailable(): boolean
+/**
+ * Check if directory cloning is supported
+ * - macOS clonefile: true (supports directories)
+ * - Linux FICLONE: false (files only)
+ */
+export declare function supportsDirectory(): boolean
+/**
+ * Get the current platform
+ * Returns "darwin" or "linux"
+ */
+export declare function getPlatform(): string

package/index.js

@@ -0,0 +1,320 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'vibe-native.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./vibe-native.android-arm64.node')
+          } else {
+            nativeBinding = require('@kexi/vibe-native-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'vibe-native.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./vibe-native.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@kexi/vibe-native-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'vibe-native.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./vibe-native.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@kexi/vibe-native-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'vibe-native.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./vibe-native.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@kexi/vibe-native-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'vibe-native.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./vibe-native.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@kexi/vibe-native-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'vibe-native.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./vibe-native.darwin-universal.node')
+      } else {
+        nativeBinding = require('@kexi/vibe-native-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'vibe-native.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./vibe-native.darwin-x64.node')
+          } else {
+            nativeBinding = require('@kexi/vibe-native-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'vibe-native.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./vibe-native.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@kexi/vibe-native-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'vibe-native.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./vibe-native.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@kexi/vibe-native-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'vibe-native.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./vibe-native.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@kexi/vibe-native-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'vibe-native.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./vibe-native.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@kexi/vibe-native-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'vibe-native.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./vibe-native.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@kexi/vibe-native-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'vibe-native.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./vibe-native.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@kexi/vibe-native-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'vibe-native.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./vibe-native.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@kexi/vibe-native-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'vibe-native.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./vibe-native.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@kexi/vibe-native-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'vibe-native.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./vibe-native.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@kexi/vibe-native-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'vibe-native.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./vibe-native.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@kexi/vibe-native-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'vibe-native.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./vibe-native.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@kexi/vibe-native-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { cloneSync, cloneAsync, clone, isAvailable, supportsDirectory, getPlatform } = nativeBinding
+
+module.exports.cloneSync = cloneSync
+module.exports.cloneAsync = cloneAsync
+module.exports.clone = clone
+module.exports.isAvailable = isAvailable
+module.exports.supportsDirectory = supportsDirectory
+module.exports.getPlatform = getPlatform

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@kexi/vibe-native",
+  "version": "0.12.5",
+  "description": "Native clone operations for vibe CLI (clonefile on macOS, FICLONE on Linux)",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "name": "vibe-native",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-apple-darwin",
+        "aarch64-apple-darwin",
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-gnu"
+      ]
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "*.node"
+  ],
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "prepublishOnly": "napi prepublish -t npm",
+    "version": "napi version"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kexi/vibe.git",
+    "directory": "packages/@kexi/vibe-native"
+  },
+  "keywords": [
+    "clonefile",
+    "ficlone",
+    "cow",
+    "copy-on-write",
+    "native",
+    "napi-rs"
+  ],
+  "author": "kexi",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}