@archildata/just-bash

Archil filesystem adapter for just-bash - run bash commands against Archil distributed filesystems.

Launch an interactive shell against your Archil disk:

ARCHIL_TOKEN=adt_xxx npx @archildata/just-bash aws-us-east-1 myaccount/mydisk

Installation

npm install @archildata/just-bash @archildata/client just-bash

Quick Start

import { ArchilClient } from '@archildata/client';
import { ArchilFs } from '@archildata/just-bash';
import { Bash } from 'just-bash';

// Connect to Archil
const client = await ArchilClient.connect({
  region: 'aws-us-east-1',
  diskName: 'myaccount/mydisk',
  authToken: 'adt_xxx', // or omit for IAM auth
});

// Create filesystem adapter
const fs = await ArchilFs.create(client);

// Use with just-bash
const bash = new Bash({ fs });

// Run commands
const result = await bash.exec('ls -la /');
console.log(result.stdout);

// Read files
const content = await bash.exec('cat /myfile.txt');

// Close when done
await client.close();

Writing Files (Delegations)

Archil uses a delegation system for write access. Before writing, you need to "checkout" the directory or file:

// 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);

For shared/multi-client access, use force to revoke existing delegations:

await client.checkout(inodeId, { force: true });

With User Context

Specify a Unix user context for permission checks:

const fs = await ArchilFs.create(client, {
  user: { uid: 1000, gid: 1000 }
});

Interactive Shell

The package includes an interactive shell for testing:

# Positional arguments (recommended)
npx @archildata/just-bash aws-us-east-1 myaccount/mydisk

# With flags
npx @archildata/just-bash --region aws-us-east-1 --disk myaccount/mydisk

# With token (use env var to keep out of shell history)
ARCHIL_TOKEN=xxx npx @archildata/just-bash aws-us-east-1 myaccount/mydisk

# With debug logging
npx @archildata/just-bash aws-us-east-1 myaccount/mydisk --log-level debug

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

ArchilFs

const fs = await ArchilFs.create(client: ArchilClient, options?: {
  user?: UnixUser;
  subdirectory?: string;
})

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

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

Enable debug logging with the DEBUG environment variable:

# Enable archil:fs logging
DEBUG=archil:fs node myapp.js

# Enable all archil debug logging
DEBUG=archil:* node myapp.js

Performance

• Chunked reads - Large files read in 4 MiB chunks
• Native protocol - Direct Archil protocol access, no FUSE overhead

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).

License

MIT