@archildata/just-bash 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+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.

package/README.md

@@ -0,0 +1,139 @@
+# @archildata/just-bash
+
+Archil filesystem adapter for [just-bash](https://github.com/anthropics/just-bash) - run bash commands against Archil distributed filesystems.
+
+## Installation
+
+```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 { 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 = new ArchilFs(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:
+
+```typescript
+// Get the inode ID for a path
+const inodeId = await fs.resolveInodeId('/mydir');
+
+// Checkout to get write access
+await client.checkout(inodeId, false); // false = don't force
+
+// 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:
+
+```typescript
+await client.checkout(inodeId, true); // force = true
+```
+
+## With User Context
+
+Specify a Unix user context for permission checks:
+
+```typescript
+const fs = new ArchilFs(client, {
+  user: { uid: 1000, gid: 1000 }
+});
+```
+
+## Interactive Shell
+
+The package includes an interactive shell for testing:
+
+```bash
+ARCHIL_REGION=aws-us-east-1 ARCHIL_DISK=myaccount/mydisk ARCHIL_TOKEN=xxx npx @archildata/just-bash
+```
+
+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`
+
+```typescript
+new ArchilFs(client: ArchilClient, options?: { user?: UnixUser })
+```
+
+#### 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
+- `clearCache()` - Clear path cache
+
+## Debugging
+
+Enable debug logging with the `DEBUG` environment variable:
+
+```bash
+# Enable archil:fs logging
+DEBUG=archil:fs node myapp.js
+
+# Enable all archil debug logging
+DEBUG=archil:* node myapp.js
+```
+
+## Performance
+
+- **Path-to-inode caching** - Avoids repeated directory lookups
+- **Chunked reads** - Large files read in 4 MiB chunks
+- **Native protocol** - Direct Archil protocol access, no FUSE overhead
+
+## License
+
+MIT

package/bin/shell.ts

@@ -0,0 +1,276 @@
+#!/usr/bin/env npx tsx
+/**
+ * Interactive just-bash shell with Archil filesystem
+ *
+ * Usage:
+ *   ARCHIL_REGION=aws-us-east-1 ARCHIL_DISK=myaccount/mydisk ARCHIL_TOKEN=xxx npx tsx bin/shell.ts
+ */
+
+import * as readline from "readline";
+import { ArchilClient } from "@archildata/client";
+import { Bash } from "just-bash";
+import { ArchilFs } from "../src/ArchilFs.js";
+
+async function main() {
+  const region = process.env.ARCHIL_REGION;
+  const diskName = process.env.ARCHIL_DISK;
+  const authToken = process.env.ARCHIL_TOKEN;
+  const logLevel = process.env.ARCHIL_LOG_LEVEL; // e.g., "debug", "info", "warn", "error", "trace"
+
+  if (!region || !diskName) {
+    console.error("Missing required environment variables:");
+    console.error("  ARCHIL_REGION    - e.g., aws-us-east-1");
+    console.error("  ARCHIL_DISK      - e.g., myaccount/mydisk");
+    console.error("  ARCHIL_TOKEN     - (optional) auth token, defaults to IAM");
+    console.error("  ARCHIL_LOG_LEVEL - (optional) log level: trace, debug, info, warn, error");
+    console.error("");
+    console.error("Usage:");
+    console.error("  ARCHIL_REGION=aws-us-east-1 ARCHIL_DISK=myaccount/mydisk npx tsx bin/shell.ts");
+    console.error("");
+    console.error("For debug logging:");
+    console.error("  ARCHIL_LOG_LEVEL=debug ARCHIL_REGION=... ARCHIL_DISK=... npx tsx bin/shell.ts");
+    process.exit(1);
+  }
+
+  console.log("Connecting to Archil...");
+  console.log(`  Region: ${region}`);
+  console.log(`  Disk: ${diskName}`);
+  console.log(`  Auth: ${authToken ? "token" : "IAM"}`);
+  if (logLevel) {
+    console.log(`  Log level: ${logLevel}`);
+  }
+  console.log("");
+
+  let client: ArchilClient;
+  try {
+    client = await ArchilClient.connect({
+      region,
+      diskName,
+      authToken: authToken || undefined,
+      logLevel,
+    });
+    console.log("Connected!");
+  } catch (err) {
+    console.error("Failed to connect:", err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+
+  // Create filesystem adapter
+  const fs = new ArchilFs(client);
+
+  // Create bash environment
+  const bash = new Bash({ fs });
+
+  // Cleanup function to release delegations and close connection
+  let cleaningUp = false;
+  const cleanup = async (signal?: string) => {
+    if (cleaningUp) return;
+    cleaningUp = true;
+
+    if (signal) {
+      console.log(`\nReceived ${signal}, cleaning up...`);
+    } else {
+      console.log("\nGoodbye!");
+    }
+
+    try {
+      // close() releases all delegations and cleans up resources
+      const released = await client.close();
+      if (released > 0) {
+        console.log(`Released ${released} delegation${released > 1 ? 's' : ''}`);
+      }
+    } catch (err) {
+      console.error("Error during cleanup:", err instanceof Error ? err.message : err);
+    }
+
+    process.exit(0);
+  };
+
+  // Handle signals for graceful shutdown
+  process.on('SIGINT', () => cleanup('SIGINT'));
+  process.on('SIGTERM', () => cleanup('SIGTERM'));
+  process.on('SIGHUP', () => cleanup('SIGHUP'));
+
+  console.log("");
+  console.log("=== Archil just-bash shell ===");
+  console.log("Type bash commands to interact with the filesystem.");
+  console.log("Special commands:");
+  console.log("  archil checkout [--force] <path>  - Acquire write delegation");
+  console.log("  archil checkin <path>             - Release write delegation");
+  console.log("  archil list-delegations           - Show held delegations");
+  console.log("  archil help                       - Show archil commands");
+  console.log("Type 'exit' or Ctrl+D to quit.");
+  console.log("");
+
+  // Create readline interface for interactive input
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: "archil$ ",
+  });
+
+  let cwd = "/";
+
+  const prompt = () => {
+    rl.setPrompt(`archil:${cwd}$ `);
+    rl.prompt();
+  };
+
+  prompt();
+
+  // Helper to resolve a path relative to cwd
+  const resolvePath = (path: string): string => {
+    if (path.startsWith("/")) {
+      return path;
+    }
+    return cwd === "/" ? "/" + path : cwd + "/" + path;
+  };
+
+  // Handle archil checkout/checkin commands
+  const handleArchilCommand = async (command: string): Promise<boolean> => {
+    const parts = command.split(/\s+/);
+    if (parts[0] !== "archil") {
+      return false;
+    }
+
+    const subcommand = parts[1];
+    const targetPath = parts[2];
+
+    if (subcommand === "checkout") {
+      // Parse flags and path
+      const args = parts.slice(2);
+      const force = args.includes("--force") || args.includes("-f");
+      const pathArg = args.find(a => !a.startsWith("-"));
+
+      if (!pathArg) {
+        console.error("Usage: archil checkout [--force|-f] <path>");
+        return true;
+      }
+      const fullPath = resolvePath(pathArg);
+      try {
+        const inodeId = await fs.resolveInodeId(fullPath);
+        await client.checkout(inodeId, force);
+        console.log(`Checked out: ${fullPath} (inode ${inodeId})${force ? " (forced)" : ""}`);
+      } catch (err) {
+        console.error(`Failed to checkout ${fullPath}:`, err instanceof Error ? err.message : err);
+      }
+      return true;
+    }
+
+    if (subcommand === "checkin") {
+      if (!targetPath) {
+        console.error("Usage: archil checkin <path>");
+        return true;
+      }
+      const fullPath = resolvePath(targetPath);
+      try {
+        const inodeId = await fs.resolveInodeId(fullPath);
+        await client.checkin(inodeId);
+        console.log(`Checked in: ${fullPath} (inode ${inodeId})`);
+      } catch (err) {
+        console.error(`Failed to checkin ${fullPath}:`, err instanceof Error ? err.message : err);
+      }
+      return true;
+    }
+
+    if (subcommand === "list-delegations" || subcommand === "delegations") {
+      try {
+        const delegations = client.listDelegations();
+        if (delegations.length === 0) {
+          console.log("No delegations held");
+        } else {
+          console.log("Delegations:");
+          for (const d of delegations) {
+            console.log(`  inode ${d.inodeId}: ${d.state}`);
+          }
+        }
+      } catch (err) {
+        console.error("Failed to list delegations:", err instanceof Error ? err.message : err);
+      }
+      return true;
+    }
+
+    if (subcommand === "help" || !subcommand) {
+      console.log("Archil commands:");
+      console.log("  archil checkout [--force|-f] <path>  - Acquire write delegation");
+      console.log("  archil checkin <path>                - Release write delegation");
+      console.log("  archil list-delegations              - Show held delegations");
+      console.log("  archil help                          - Show this help message");
+      console.log("");
+      console.log("The --force flag revokes any existing delegation from other clients.");
+      return true;
+    }
+
+    console.error(`Unknown archil command: ${subcommand}`);
+    console.error("Run 'archil help' for available commands");
+    return true;
+  };
+
+  rl.on("line", async (line) => {
+    const trimmed = line.trim();
+
+    if (trimmed === "exit" || trimmed === "quit") {
+      await cleanup();
+      return;
+    }
+
+    if (!trimmed) {
+      prompt();
+      return;
+    }
+
+    // Pause readline while we process the command
+    rl.pause();
+
+    try {
+      // Check for archil commands first
+      if (trimmed.startsWith("archil")) {
+        await handleArchilCommand(trimmed);
+        rl.resume();
+        prompt();
+        return;
+      }
+
+      // Execute command with current working directory
+      const result = await bash.exec(trimmed, {
+        cwd,
+        env: {
+          HOME: "/",
+          USER: "archil",
+          PWD: cwd,
+        },
+      });
+
+      // Print output
+      if (result.stdout) {
+        process.stdout.write(result.stdout);
+        if (!result.stdout.endsWith("\n")) {
+          console.log("");
+        }
+      }
+      if (result.stderr) {
+        process.stderr.write(result.stderr);
+        if (!result.stderr.endsWith("\n")) {
+          console.error("");
+        }
+      }
+
+      // Update cwd if command changed it
+      if (result.env?.PWD && result.env.PWD !== cwd) {
+        cwd = result.env.PWD;
+      }
+    } catch (err) {
+      console.error("Error:", err instanceof Error ? err.message : err);
+    }
+
+    rl.resume();
+    prompt();
+  });
+
+  rl.on("close", () => cleanup());
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});