@archildata/just-bash 0.1.13 → 0.8.2

package/README.md

@@ -1,155 +1,145 @@
 # @archildata/just-bash
 
-Archil filesystem adapter for just-bash - run bash commands against Archil distributed filesystems.
+Run bash commands against your cloud storage through [Archil](https://archil.com) — no local mount required. Works in scripts, CI pipelines, and interactive sessions.
 
-Launch an interactive shell against your Archil disk:
+## Quick Start
+
+If you already have an Archil disk set up (see [@archildata/client](https://www.npmjs.com/package/@archildata/client) for setup), you can start a shell in one command:
 
 ```bash
-ARCHIL_TOKEN=adt_xxx npx @archildata/just-bash aws-us-east-1 myaccount/mydisk
+ARCHIL_TOKEN=my-secret-mount-token npx @archildata/just-bash aws-us-east-1 myaccount/my-disk
 ```
 
-## Installation
+This drops you into an interactive shell. The files you see are the contents of your cloud bucket:
+
+```
+$ ls
+data/  logs/  config.json
+
+$ cat config.json
+{"version": 2, "debug": false}
+
+$ echo "hello from archil" > greeting.txt
+```
+
+Everything you do here — reads, writes, renames, deletes — goes through Archil to your bucket.
+
+## Using in Your Code
+
+The interactive shell is great for poking around, but you can also run bash commands from your own code. This is useful for scripts, CI pipelines, AI agents, or anywhere you want to run shell commands against your cloud storage.
 
 ```bash
 npm install @archildata/just-bash @archildata/client just-bash
 ```
 
-## Quick Start
-
 ```typescript
 import { ArchilClient } from '@archildata/client';
-import { ArchilFs } from '@archildata/just-bash';
+import { ArchilFs, createArchilCommand } from '@archildata/just-bash';
 import { Bash } from 'just-bash';
 
-// Connect to Archil
+// Connect to your disk
 const client = await ArchilClient.connect({
   region: 'aws-us-east-1',
-  diskName: 'myaccount/mydisk',
-  authToken: 'adt_xxx', // or omit for IAM auth
+  diskName: 'myaccount/my-disk',
+  authToken: 'my-secret-mount-token',
 });
 
-// Create filesystem adapter
-const fs = new ArchilFs(client);
-
-// Use with just-bash
-const bash = new Bash({ fs });
+// Create a filesystem adapter and a bash executor
+const fs = await ArchilFs.create(client);
+const bash = new Bash({
+  fs,
+  customCommands: [createArchilCommand(client, fs)],
+});
 
-// Run commands
+// Run commands just like you would in a terminal
 const result = await bash.exec('ls -la /');
 console.log(result.stdout);
 
-// Read files
-const content = await bash.exec('cat /myfile.txt');
+// Write a file
+await bash.exec('echo "hello world" > /greeting.txt');
+
+// Read it back
+const cat = await bash.exec('cat /greeting.txt');
+console.log(cat.stdout); // "hello world"
 
-// Close when done
+// Clean up
 await client.close();
 ```
 
-## Writing Files (Delegations)
+## Using the Filesystem Adapter Directly
 
-Archil uses a delegation system for write access. Before writing, you need to "checkout" the directory or file:
+If you don't need bash and just want standard file operations, you can use `ArchilFs` on its own. It works like Node.js `fs`:
 
 ```typescript
-// Get the inode ID for a path
-const inodeId = await fs.resolveInodeId('/mydir');
-
-// Checkout to get write access
-await client.checkout(inodeId);
-
-// Now you can write
-await bash.exec('echo "hello" > /mydir/newfile.txt');
-
-// Release the delegation when done
-await client.checkin(inodeId);
+const fs = await ArchilFs.create(client);
+
+await fs.writeFile('/notes.txt', 'some content');
+const content = await fs.readFile('/notes.txt');
+const entries = await fs.readdir('/');
+const stats = await fs.stat('/notes.txt');
+await fs.mkdir('/mydir', { recursive: true });
+await fs.cp('/notes.txt', '/mydir/notes-copy.txt');
+await fs.rm('/notes.txt');
 ```
 
-For shared/multi-client access, use `force` to revoke existing delegations:
-
-```typescript
-await client.checkout(inodeId, { force: true });
-```
+## Writing Files (Delegations)
 
-## With User Context
+Archil uses a delegation system for writes. When multiple clients connect to the same disk, delegations coordinate who can write to what. Before writing to a file or directory, you "check out" a delegation on it. When you're done, you "check in" to release it.
 
-Specify a Unix user context for permission checks:
+In the interactive shell, use the built-in `archil` command:
 
-```typescript
-const fs = new ArchilFs(client, {
-  user: { uid: 1000, gid: 1000 }
-});
+```
+$ archil checkout /mydir
+$ echo "hello" > /mydir/newfile.txt
+$ archil checkin /mydir
 ```
 
-## Interactive Shell
-
-The package includes an interactive shell for testing:
-
-```bash
-# Positional arguments (recommended)
-npx @archildata/just-bash aws-us-east-1 myaccount/mydisk
+In code, use the client directly:
 
-# With flags
-npx @archildata/just-bash --region aws-us-east-1 --disk myaccount/mydisk
+```typescript
+const inodeId = await fs.resolveInodeId('/mydir');
+await client.checkout(inodeId);
 
-# With token (use env var to keep out of shell history)
-ARCHIL_TOKEN=xxx npx @archildata/just-bash aws-us-east-1 myaccount/mydisk
+await bash.exec('echo "hello" > /mydir/newfile.txt');
 
-# With debug logging
-npx @archildata/just-bash aws-us-east-1 myaccount/mydisk --log-level debug
+await client.checkin(inodeId);
 ```
 
-Shell commands:
-- Standard bash commands (`ls`, `cat`, `echo`, etc.)
-- `archil checkout [--force] <path>` - Acquire write delegation
-- `archil checkin <path>` - Release write delegation
-- `archil help` - Show archil commands
-
-## API
+## Subdirectory Mounting
 
-### `ArchilFs`
+You can mount a subdirectory of a disk instead of the root. This is useful when your bucket has a project nested inside it:
 
-```typescript
-new ArchilFs(client: ArchilClient, options?: { user?: UnixUser })
+```bash
+ARCHIL_TOKEN=my-secret-mount-token npx @archildata/just-bash aws-us-east-1 myaccount/my-disk:/data/project
 ```
 
-#### Read Operations
-- `readFile(path, encoding?)` - Read file as string
-- `readFileBuffer(path)` - Read file as Uint8Array
-- `readdir(path)` - List directory entries
-- `stat(path)` / `lstat(path)` - Get file stats
-- `exists(path)` - Check if path exists
-- `readlink(path)` - Read symlink target
+## Interactive Shell Reference
 
-#### Write Operations
-- `writeFile(path, content)` - Write file
-- `appendFile(path, content)` - Append to file
-- `mkdir(path, options?)` - Create directory
-- `rm(path, options?)` - Delete file/directory
-- `cp(src, dest, options?)` - Copy
-- `mv(src, dest)` - Move/rename
-- `symlink(target, path)` - Create symlink
-
-#### Utilities
-- `resolveInodeId(path)` - Get inode ID for delegation operations
-
-## Debugging
+```bash
+# Basic usage
+npx @archildata/just-bash <region> <org>/<disk>
 
-Enable debug logging with the `DEBUG` environment variable:
+# With mount token
+ARCHIL_TOKEN=xxx npx @archildata/just-bash aws-us-east-1 myaccount/my-disk
 
-```bash
-# Enable archil:fs logging
-DEBUG=archil:fs node myapp.js
+# With subdirectory
+npx @archildata/just-bash aws-us-east-1 myaccount/my-disk:/path/to/subdir
 
-# Enable all archil debug logging
-DEBUG=archil:* node myapp.js
+# With debug logging
+npx @archildata/just-bash aws-us-east-1 myaccount/my-disk --log-level debug
 ```
 
-## Performance
+Shell commands:
+- Standard bash commands (`ls`, `cat`, `echo`, `cp`, `mv`, `rm`, etc.)
+- `archil checkout [--force] <path>` — acquire write delegation
+- `archil checkin <path>` — release write delegation
+- `archil list-delegations` — show currently held delegations
+- `archil help` — show archil commands
 
-- **Chunked reads** - Large files read in 4 MiB chunks
-- **Native protocol** - Direct Archil protocol access, no FUSE overhead
+## Platform Support
 
-> **Note:** For best performance, run your application in the same region as your Archil disk (e.g., if your disk is in `aws-us-east-1`, deploy your app to AWS us-east-1).
+Requires **Linux** (x64 or arm64, glibc) or **macOS** (Apple Silicon / arm64) for the native filesystem client.
 
-## License
+## Support
 
-MIT
+Questions, feature requests, or issues? Reach us at **support@archil.com**.