disk 0.8.0 → 0.8.8

package/{LICENSE.md → LICENSE}

@@ -1,5 +1,6 @@
-# The MIT License (MIT)
-Copyright (c) 2013 Jonas Hermsmeier
+MIT License
+
+Copyright (c) 2026 Archil, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -11,10 +12,10 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
-DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
-OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
-OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,119 +1,152 @@
-# Disk
-[![npm](https://img.shields.io/npm/v/disk.svg?style=flat-square)](https://npmjs.com/package/disk)
-[![npm license](https://img.shields.io/npm/l/disk.svg?style=flat-square)](https://npmjs.com/package/disk)
-[![npm downloads](https://img.shields.io/npm/dm/disk.svg?style=flat-square)](https://npmjs.com/package/disk)
-[![build status](https://img.shields.io/travis/jhermsmeier/node-disk/master.svg?style=flat-square)](https://travis-ci.org/jhermsmeier/node-disk)
-[![stability](https://img.shields.io/badge/stability-experimental-orange.svg?style=flat-square)](https://nodejs.org/api/documentation.html#documentation_stability_index)
+# disk
 
-## Install via [npm](https://npmjs.com)
+Node.js client and CLI for [Archil](https://archil.com) disks. Create disks, list and inspect them, manage who can mount them, and run commands against them — all from scripts, CI, or an interactive terminal.
 
-```sh
-$ npm install --save disk
-```
+`disk` talks to the Archil control plane over HTTPS and has no native dependencies. If you also want to mount a disk's data plane from Node (rare — most users want `disk exec` or the `archil` CLI), install [`@archildata/native`](https://www.npmjs.com/package/@archildata/native) alongside `disk`.
 
-## Related Modules
+## Install
 
-**Internals:**
+```bash
+npm install disk
+```
 
-- [MBR](https://github.com/jhermsmeier/node-mbr) – Master Boot Record
-- [GPT](https://github.com/jhermsmeier/node-gpt) – GUID Partition Table
-- [CHS](https://github.com/jhermsmeier/node-chs) – Cylinder-Head-Sector Addressing
-- [apple-partition-map](https://github.com/jhermsmeier/node-apple-partition-map) – Apple Partition Map
-- [BlockDevice](https://github.com/jhermsmeier/node-blockdevice) – Block device handling
-- [RamDisk](https://github.com/jhermsmeier/node-ramdisk) – In-memory block device
+## CLI
 
-**Block Devices:**
+```bash
+# Authenticate
+export ARCHIL_API_KEY=key-...
+export ARCHIL_REGION=aws-us-east-1
 
-- [VHD](https://github.com/jhermsmeier/node-vhd) – Microsoft Virtual Hard Disk format
-- [UDIF](https://github.com/jhermsmeier/node-udif) – Apple's DMG / UDIF (Universal Disk Image Format)
-- [UDF](https://github.com/jhermsmeier/node-udf) – OSTA Universal Disk Format
+# Create a disk — the response includes a one-time disk token you'll need to mount it
+npx disk create my-disk
 
-**File Systems:**
+# List and inspect
+npx disk list
+npx disk get dsk-abc123
 
-- [FAT32](https://github.com/jhermsmeier/node-fat32) – FAT32/16/12 file system driver
-- [ExFAT](https://github.com/jhermsmeier/node-exfat) – ExFAT file system driver
-- [HFSX](https://github.com/jhermsmeier/node-hsfx) – Apple HFS+ file system driver
-- [NTFS](https://github.com/jhermsmeier/node-ntfs) – NTFS file system driver
+# Run a command against the disk's contents — Archil spins up a container with the disk
+# mounted, runs the command, and returns stdout/stderr/exit code.
+npx disk dsk-abc123 exec "ls -la /mnt"
 
-## Usage
+# Delete
+npx disk delete dsk-abc123
 
-```js
-var Disk = require( 'disk' )
+# Manage account-level API keys
+npx disk api-keys list
+npx disk api-keys create ci-bot
+npx disk api-keys delete key-abc123
 ```
 
-Set up a device to work with.
-This can be anything with a [blockdevice](https://github.com/jhermsmeier/node-blockdevice) compatible API.
+`list` and `get` pretty-print tables by default; pass `-o json` to pipe into `jq`. Credentials come from `ARCHIL_API_KEY` / `ARCHIL_REGION`, or `--api-key` / `--region` / `--base-url` flags.
+
+## Library
+
+The recommended pattern is a module-namespace import:
+
+```ts
+import * as archil from "disk";
 
-```js
-var device = new BlockDevice({
-  path: BlockDevice.getPath( 0 )
-})
+// Configure once per process — falls back to ARCHIL_API_KEY / ARCHIL_REGION env vars.
+archil.configure({ apiKey: process.env.ARCHIL_API_KEY, region: "aws-us-east-1" });
+
+// Create a disk. `token` here is the disk token — the one-time credential for mounting.
+const { disk, token } = await archil.createDisk({ name: "my-disk" });
+console.log(`Created ${disk.id}, disk token: ${token}`);
+
+// List and look up disks
+const all = await archil.listDisks();
+const d = await archil.getDisk(disk.id);
 ```
 
-Create a disk:
+Per-disk operations are methods on the `Disk` object itself, not top-level functions:
+
+```ts
+const d = await archil.getDisk("dsk-abc123");
+
+// Run a command in a container with the disk mounted
+const { stdout, stderr, exitCode } = await d.exec("ls -la /mnt && cat /mnt/config.json");
+
+// Manage who can mount the disk
+const user = await d.addUser({ type: "token", nickname: "ci" });
+await d.removeUser("token", user.identifier!);
 
-```js
-var disk = new Disk( device )
+// Delete
+await d.delete();
 ```
 
-Open the device:
+API keys live at the account level, so those helpers are top-level:
 
-```js
-// This also attempts to detect it's block size if unspecified,
-// as well as reading the MBR & GPT on the device
-disk.open( function( error ) {})
+```ts
+await archil.listApiKeys();
+await archil.createApiKey({ name: "ci-bot", description: "GitHub Actions" });
+await archil.deleteApiKey("key-abc123");
 ```
 
-Read or write the MBR (`disk.mbr`) from or to the device:
+### Named imports
 
-```js
-disk.readMBR( function( error, mbr ) {})
-disk.writeMBR( function( error ) {})
+If you prefer named imports over the namespace style, they work the same way:
+
+```ts
+import { createDisk, getDisk, listDisks, configure } from "disk";
 ```
 
-Read or write the GPT (`disk.gpt`) from or to the device:
+### Multiple accounts or regions
+
+For multi-tenant scripts, instantiate `Archil` directly instead of using the module-level `configure`:
+
+```ts
+import { Archil } from "disk";
 
-```js
-disk.readGPT( function( error, gpt ) {})
-disk.writeGPT( function( error ) {})
+const prod = new Archil({ apiKey: prodKey, region: "aws-us-east-1" });
+const staging = new Archil({ apiKey: stagingKey, region: "aws-us-east-1" });
+
+const prodDisks = await prod.disks.list();
+const stagingDisks = await staging.disks.list();
 ```
 
-Verify the backup GPT;
-NOTE: The callback will be called with an error *and*
-the backup GPT if it doesn't verify.
+## Connecting to a disk's data plane
+
+To run a command against a disk, use `Disk.exec()` — it returns stdout, stderr, and an exit code from an Archil-managed container with the disk pre-mounted. No local filesystem involved.
 
-```js
-disk.verifyGPT( function( error, backupGPT ) {})
+To mount a disk as a real filesystem on your machine, use the [`archil`](https://archil.com) CLI — it mounts through the OS kernel via FUSE, so any program can read and write files with standard APIs.
+
+For the rare case where you need raw Archil protocol access from Node.js (inodes, delegations, byte-level reads), install [`@archildata/native`](https://www.npmjs.com/package/@archildata/native) alongside `disk`:
+
+```bash
+npm install disk @archildata/native
 ```
 
-Close the device:
+Then `Disk.mount()` lazy-loads the native client:
 
-```js
-disk.close( function( error ) {})
+```ts
+import { getDisk } from "disk";
+
+const d = await getDisk("dsk-abc123");
+const client = await d.mount({ authToken: "<disk-token>" });
+// `client` is an ArchilClient from @archildata/native — see that package's README.
+await client.close();
 ```
 
-## API
+`@archildata/native` supports Linux (x64 / arm64, glibc) and macOS (arm64). On other platforms, `mount()` throws; the rest of `disk` still works.
+
+## Supported regions
 
-#### Disk
+| Region            | Provider |
+| ----------------- | -------- |
+| `aws-us-east-1`   | AWS      |
+| `aws-us-west-2`   | AWS      |
+| `aws-eu-west-1`   | AWS      |
+| `gcp-us-central1` | GCP      |
 
-- Disk.MBR: See [mbr](https://github.com/jhermsmeier/node-mbr)
-- Disk.GPT: See [gpt](https://github.com/jhermsmeier/node-gpt)
+## FAQ
 
-#### new Disk( device )
+### What's the difference between an API key and a disk token?
 
-**Properties:**
+Archil has two credential types, and the examples above use both:
 
-- **device**
-- **mbr**
-- **gpt**
+- **API key** — account-level credential for the control plane. You use one whenever you call `disk` (CLI or library). Create and manage them at [console.archil.com](https://console.archil.com) or with `disk api-keys create`. Goes in the `ARCHIL_API_KEY` env var or the `--api-key` flag.
+- **Disk token** — per-disk credential that lets a client mount a specific disk. Created automatically when you `disk create <name>` (the value is shown once; save it). You don't need one to run `disk` itself — only when something is actually mounting a disk.
 
-**Methods:**
+## Support
 
-- **open( callback )**
-- **close( callback )**
-- **getEFIPart()**
-- **readMBR( callback )**
-- **writeMBR( callback )**
-- **readGPT( callback )**
-- **writeGPT( callback )**
-- **writeGPT( callback )**: Not implemented
+Questions, feature requests, or issues? Reach us at **support@archil.com**.