@archildata/just-bash 0.8.18 → 0.8.19

package/dist/index.cjs

@@ -1,691 +1,646 @@
-"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
 var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  ArchilFs: () => ArchilFs,
-  createArchilCommand: () => createArchilCommand,
-  createArchilFs: () => createArchilFs
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/ArchilFs.ts
-var import_debug = __toESM(require("debug"), 1);
-var import_native = require("@archildata/native");
-var debug = (0, import_debug.default)("archil:fs");
-var ArchilFs = class _ArchilFs {
-  client;
-  user;
-  rootInodeId = 1;
-  constructor(client, options) {
-    this.client = client;
-    this.user = options?.user;
-  }
-  /**
-   * Create an ArchilFs adapter, optionally rooted at a subdirectory.
-   *
-   * The subdirectory path is resolved eagerly: if any component does not
-   * exist or is not a directory, this method throws immediately.
-   *
-   * @param client - Connected ArchilClient instance
-   * @param options - Optional configuration
-   * @param options.user - Unix user context for permission checks
-   * @param options.subdirectory - Subdirectory to treat as the root of the filesystem
-   */
-  static async create(client, options) {
-    const fs = new _ArchilFs(client, { user: options?.user });
-    if (options?.subdirectory) {
-      const resolved = await fs.resolveFollow(options.subdirectory);
-      if (resolved.attributes.inodeType !== "Directory") {
-        throw new Error(`ENOTDIR: subdirectory '${options.subdirectory}' is not a directory`);
-      }
-      fs.rootInodeId = resolved.inodeId;
-      debug("resolved subdirectory '%s' to inode %d", options.subdirectory, fs.rootInodeId);
-    }
-    return fs;
-  }
-  // ========================================================================
-  // Path Resolution
-  // ========================================================================
-  /**
-   * Normalize a path (remove . and .., ensure leading /)
-   */
-  normalizePath(path) {
-    if (!path || path === "") {
-      return "/";
-    }
-    if (!path.startsWith("/")) {
-      path = "/" + path;
-    }
-    const parts = path.split("/").filter((p) => p !== "" && p !== ".");
-    const result = [];
-    for (const part of parts) {
-      if (part === "..") {
-        result.pop();
-      } else {
-        result.push(part);
-      }
-    }
-    return "/" + result.join("/");
-  }
-  static MAX_SYMLINKS = 40;
-  /**
-   * Resolve a path to its inode ID, walking the directory tree.
-   * Follows symlinks on intermediate components but NOT on the final
-   * component (matching lstat/readlink semantics).
-   */
-  async resolve(path, symlinkDepth = 0) {
-    const normalizedPath = this.normalizePath(path);
-    const parts = normalizedPath.split("/").filter((p) => p !== "");
-    let currentInodeId = this.rootInodeId;
-    let resolvedPath = "/";
-    for (let i = 0; i < parts.length; i++) {
-      const part = parts[i];
-      const response = await this.client.lookupInode(currentInodeId, part, { user: this.user });
-      if (response === null) {
-        throw new Error(`ENOENT: no such file or directory, '${path}'`);
-      }
-      const isLast = i === parts.length - 1;
-      if (!isLast && response.attributes.inodeType === "Symlink" && response.attributes.symlinkTarget) {
-        if (symlinkDepth >= _ArchilFs.MAX_SYMLINKS) {
-          throw new Error(`ELOOP: too many levels of symbolic links, '${path}'`);
-        }
-        const targetPath = response.attributes.symlinkTarget.startsWith("/") ? response.attributes.symlinkTarget : this.resolvePath(resolvedPath, response.attributes.symlinkTarget);
-        const remaining = parts.slice(i + 1).join("/");
-        const fullPath = remaining ? targetPath + "/" + remaining : targetPath;
-        return this.resolve(fullPath, symlinkDepth + 1);
-      }
-      resolvedPath = resolvedPath === "/" ? "/" + part : resolvedPath + "/" + part;
-      currentInodeId = response.inodeId;
-    }
-    const attributes = await this.client.getAttributes(currentInodeId, { user: this.user });
-    return { inodeId: currentInodeId, attributes };
-  }
-  /**
-   * Resolve a path, following symlinks on ALL components including the
-   * final one (like stat(2)). Use resolve() when you need lstat semantics.
-   */
-  async resolveFollow(path, symlinkDepth = 0) {
-    if (symlinkDepth >= _ArchilFs.MAX_SYMLINKS) {
-      throw new Error(`ELOOP: too many levels of symbolic links, '${path}'`);
-    }
-    const resolved = await this.resolve(path, symlinkDepth);
-    if (resolved.attributes.inodeType === "Symlink" && resolved.attributes.symlinkTarget) {
-      const targetPath = resolved.attributes.symlinkTarget.startsWith("/") ? resolved.attributes.symlinkTarget : this.resolvePath(path, "..", resolved.attributes.symlinkTarget);
-      return this.resolveFollow(targetPath, symlinkDepth + 1);
-    }
-    return resolved;
-  }
-  /**
-   * Resolve parent directory and get child name
-   */
-  async resolveParent(path) {
-    debug("resolveParent raw path=%j (bytes: %o)", path, Buffer.from(path));
-    const normalizedPath = this.normalizePath(path);
-    const lastSlash = normalizedPath.lastIndexOf("/");
-    const parentPath = lastSlash === 0 ? "/" : normalizedPath.substring(0, lastSlash);
-    const name = normalizedPath.substring(lastSlash + 1);
-    debug("resolveParent extracted name=%j (bytes: %o)", name, Buffer.from(name));
-    const { inodeId: parentInodeId } = await this.resolve(parentPath);
-    return { parentInodeId, name };
-  }
-  /**
-   * Convert InodeAttributes to FsStat
-   */
-  toStat(attrs) {
-    return {
-      isFile: attrs.inodeType === "File",
-      isDirectory: attrs.inodeType === "Directory",
-      isSymbolicLink: attrs.inodeType === "Symlink",
-      mode: attrs.mode,
-      size: Number(attrs.size),
-      mtime: new Date(attrs.mtimeMs)
-    };
-  }
-  static DIR_PAGE_SIZE = 1e3;
-  /**
-   * Read all directory entries using the paginated API.
-   */
-  async readAllDirectoryEntries(inodeId) {
-    const handle = await this.client.openDirectory(inodeId, { user: this.user });
-    try {
-      const allEntries = [];
-      let cursor;
-      for (; ; ) {
-        const page = await this.client.readDirectory(
-          inodeId,
-          handle,
-          _ArchilFs.DIR_PAGE_SIZE,
-          cursor,
-          { user: this.user }
-        );
-        allEntries.push(...page.entries);
-        if (!page.nextCursor) break;
-        cursor = page.nextCursor;
-      }
-      return allEntries;
-    } finally {
-      this.client.closeDirectory(inodeId, handle);
-    }
-  }
-  // ========================================================================
-  // IFileSystem Implementation - Read Operations
-  // ========================================================================
-  resolvePath(base, ...paths) {
-    debug("resolvePath base=%s paths=%o", base, paths);
-    let result = base;
-    for (const p of paths) {
-      if (p.startsWith("/")) {
-        result = p;
-      } else {
-        result = result.endsWith("/") ? result + p : result + "/" + p;
-      }
-    }
-    const normalized = this.normalizePath(result);
-    debug("resolvePath result=%s", normalized);
-    return normalized;
-  }
-  async readFile(path, encoding) {
-    debug("readFile path=%s encoding=%s", path, encoding);
-    try {
-      const buffer = await this.readFileBuffer(path);
-      debug("readFile got buffer length=%d", buffer.length);
-      const enc = encoding || "utf-8";
-      let result;
-      if (enc === "base64" || enc === "hex" || enc === "binary") {
-        result = Buffer.from(buffer).toString(enc);
-      } else {
-        result = new TextDecoder(enc).decode(buffer);
-      }
-      debug("readFile decoded to string length=%d", result.length);
-      return result;
-    } catch (err) {
-      debug("readFile FAILED: %O", err);
-      throw err;
-    }
-  }
-  async readFileBuffer(path) {
-    debug("readFileBuffer path=%s", path);
-    const { inodeId, attributes } = await this.resolveFollow(path);
-    debug("readFileBuffer resolved inodeId=%d type=%s size=%d", inodeId, attributes.inodeType, attributes.size);
-    if (attributes.inodeType !== "File") {
-      throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
-    }
-    const size = Number(attributes.size);
-    if (size === 0) {
-      debug("readFileBuffer file is empty, returning empty buffer");
-      return new Uint8Array(0);
-    }
-    if (size <= import_native.MAXIMUM_READ_SIZE) {
-      const buffer = await this.client.readInode(inodeId, 0, size, { user: this.user });
-      return new Uint8Array(buffer);
-    }
-    const result = new Uint8Array(size);
-    let offset = 0;
-    while (offset < size) {
-      const chunkSize = Math.min(import_native.MAXIMUM_READ_SIZE, size - offset);
-      const chunk = await this.client.readInode(inodeId, offset, chunkSize, { user: this.user });
-      result.set(new Uint8Array(chunk), offset);
-      offset += chunkSize;
-    }
-    return result;
-  }
-  async readdir(path) {
-    debug("readdir path=%s", path);
-    const { inodeId, attributes } = await this.resolveFollow(path);
-    if (attributes.inodeType !== "Directory") {
-      throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
-    }
-    const entries = await this.readAllDirectoryEntries(inodeId);
-    for (const e of entries) {
-      debug("readdir entry name=%j (bytes: %o)", e.name, Buffer.from(e.name));
-    }
-    return entries.map((e) => e.name).filter((name) => name !== "." && name !== "..");
-  }
-  async readdirWithFileTypes(path) {
-    const { inodeId, attributes } = await this.resolveFollow(path);
-    if (attributes.inodeType !== "Directory") {
-      throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
-    }
-    const entries = await this.readAllDirectoryEntries(inodeId);
-    return entries.filter((e) => e.name !== "." && e.name !== "..").map((e) => ({
-      name: e.name,
-      isFile: e.inodeType === "File",
-      isDirectory: e.inodeType === "Directory",
-      isSymbolicLink: e.inodeType === "Symlink"
-    }));
-  }
-  async stat(path) {
-    debug("stat path=%s", path);
-    const { attributes } = await this.resolveFollow(path);
-    return this.toStat(attributes);
-  }
-  async lstat(path) {
-    debug("lstat path=%s", path);
-    const { attributes } = await this.resolve(path);
-    return this.toStat(attributes);
-  }
-  async exists(path) {
-    debug("exists path=%s", path);
-    try {
-      await this.resolve(path);
-      debug("exists path=%s -> true", path);
-      return true;
-    } catch {
-      debug("exists path=%s -> false", path);
-      return false;
-    }
-  }
-  async readlink(path) {
-    const { attributes } = await this.resolve(path);
-    if (attributes.inodeType !== "Symlink") {
-      throw new Error(`EINVAL: invalid argument, readlink '${path}'`);
-    }
-    return attributes.symlinkTarget || "";
-  }
-  async realpath(path, symlinkDepth = 0) {
-    const normalizedPath = this.normalizePath(path);
-    const parts = normalizedPath.split("/").filter((p) => p !== "");
-    let resolvedPath = "/";
-    let currentInodeId = this.rootInodeId;
-    for (const part of parts) {
-      const response = await this.client.lookupInode(currentInodeId, part, { user: this.user });
-      if (response === null) {
-        throw new Error(`ENOENT: no such file or directory, realpath '${path}'`);
-      }
-      const attrs = response.attributes;
-      if (attrs.inodeType === "Symlink" && attrs.symlinkTarget) {
-        if (symlinkDepth >= _ArchilFs.MAX_SYMLINKS) {
-          throw new Error(`ELOOP: too many levels of symbolic links, '${path}'`);
-        }
-        const targetPath = attrs.symlinkTarget.startsWith("/") ? attrs.symlinkTarget : this.resolvePath(resolvedPath, attrs.symlinkTarget);
-        const resolved = await this.realpath(targetPath, symlinkDepth + 1);
-        resolvedPath = resolved;
-        const { inodeId } = await this.resolve(resolved);
-        currentInodeId = inodeId;
-      } else {
-        resolvedPath = resolvedPath === "/" ? "/" + part : resolvedPath + "/" + part;
-        currentInodeId = response.inodeId;
-      }
-    }
-    return resolvedPath;
-  }
-  // ========================================================================
-  // IFileSystem Implementation - Write Operations
-  // ========================================================================
-  async writeFile(path, content) {
-    debug("writeFile path=%s contentLength=%d", path, content.length);
-    const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
-    let resolved;
-    try {
-      resolved = await this.resolveFollow(path);
-    } catch (err) {
-      if (err instanceof Error && err.message.includes("ENOENT")) {
-        resolved = null;
-      } else {
-        throw err;
-      }
-    }
-    if (resolved !== null) {
-      debug("writeFile resolved existing file path=%s inodeId=%d", path, resolved.inodeId);
-      if (resolved.attributes.inodeType !== "File") {
-        throw new Error(`EISDIR: illegal operation on a directory, write '${path}'`);
-      }
-      const realPath = await this.realpath(path);
-      const { parentInodeId: parentInodeId2, name: name2 } = await this.resolveParent(realPath);
-      const tmpName = `.~tmp-${Math.random().toString(36).slice(2)}`;
-      debug("writeFile atomic overwrite via temp=%s", tmpName);
-      const tmpResult = await this.client.create(
-        parentInodeId2,
-        tmpName,
-        {
-          inodeType: "File",
-          uid: resolved.attributes.uid,
-          gid: resolved.attributes.gid,
-          mode: resolved.attributes.mode
-        },
-        { user: this.user }
-      );
-      try {
-        await this.client.writeData(tmpResult.inodeId, 0, Buffer.from(data), { user: this.user });
-        await this.client.rename(parentInodeId2, tmpName, parentInodeId2, name2, { user: this.user });
-        debug("writeFile atomic overwrite succeeded");
-      } catch (writeErr) {
-        try {
-          await this.client.unlink(parentInodeId2, tmpName, { user: this.user });
-        } catch {
-        }
-        throw writeErr;
-      }
-      return;
-    }
-    debug("writeFile file doesn't exist, creating: %s", path);
-    const { parentInodeId, name } = await this.resolveParent(path);
-    debug("writeFile resolved parent parentInodeId=%d name=%s", parentInodeId, name);
-    const result = await this.client.create(
-      parentInodeId,
-      name,
-      {
-        inodeType: "File",
-        uid: this.user?.uid ?? 0,
-        gid: this.user?.gid ?? 0,
-        mode: 420
-      },
-      { user: this.user }
-    );
-    debug("writeFile create succeeded inodeId=%d", result.inodeId);
-    await this.client.writeData(result.inodeId, 0, Buffer.from(data), { user: this.user });
-    debug("writeFile write succeeded");
-  }
-  async appendFile(path, content) {
-    const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
-    let inodeId;
-    let size;
-    try {
-      const resolved = await this.resolveFollow(path);
-      if (resolved.attributes.inodeType !== "File") {
-        throw new Error(`EISDIR: illegal operation on a directory, write '${path}'`);
-      }
-      inodeId = resolved.inodeId;
-      size = Number(resolved.attributes.size);
-    } catch (err) {
-      if (err instanceof Error && err.message.includes("ENOENT")) {
-        await this.writeFile(path, data);
-        return;
-      }
-      throw err;
-    }
-    await this.client.writeData(inodeId, size, Buffer.from(data), { user: this.user });
-  }
-  async mkdir(path, options) {
-    const normalizedPath = this.normalizePath(path);
-    if (options?.recursive) {
-      const parts = normalizedPath.split("/").filter((p) => p !== "");
-      let currentPath = "";
-      for (const part of parts) {
-        currentPath += "/" + part;
-        const exists = await this.exists(currentPath);
-        if (exists) {
-          continue;
-        }
-        await this.mkdirSingle(currentPath);
-      }
-    } else {
-      await this.mkdirSingle(normalizedPath);
-    }
-  }
-  async mkdirSingle(path) {
-    const { parentInodeId, name } = await this.resolveParent(path);
-    await this.client.create(
-      parentInodeId,
-      name,
-      {
-        inodeType: "Directory",
-        uid: this.user?.uid ?? 0,
-        gid: this.user?.gid ?? 0,
-        mode: 493
-      },
-      { user: this.user }
-    );
-  }
-  async rm(path, options) {
-    let resolved;
-    try {
-      resolved = await this.resolve(path);
-    } catch (err) {
-      if (err instanceof Error && err.message.includes("ENOENT")) {
-        if (options?.force) {
-          return;
-        }
-        throw err;
-      }
-      throw err;
-    }
-    if (resolved.attributes.inodeType === "Directory") {
-      if (!options?.recursive) {
-        throw new Error(`EISDIR: illegal operation on a directory, rm '${path}'`);
-      }
-      const entries = await this.readdir(path);
-      for (const entry of entries) {
-        await this.rm(this.resolvePath(path, entry), options);
-      }
-    }
-    const { parentInodeId, name } = await this.resolveParent(path);
-    await this.client.unlink(parentInodeId, name, { user: this.user });
-  }
-  async cp(src, dest, options) {
-    const srcResolved = await this.resolveFollow(src);
-    if (srcResolved.attributes.inodeType === "Directory") {
-      if (!options?.recursive) {
-        throw new Error(`EISDIR: illegal operation on a directory, cp '${src}'`);
-      }
-      await this.mkdir(dest, { recursive: true });
-      const entries = await this.readdir(src);
-      for (const entry of entries) {
-        await this.cp(
-          this.resolvePath(src, entry),
-          this.resolvePath(dest, entry),
-          options
-        );
-      }
-    } else {
-      const content = await this.readFileBuffer(src);
-      await this.writeFile(dest, content);
-    }
-  }
-  async mv(src, dest) {
-    const { parentInodeId: srcParentInodeId, name: srcName } = await this.resolveParent(src);
-    const { parentInodeId: destParentInodeId, name: destName } = await this.resolveParent(dest);
-    await this.client.rename(
-      srcParentInodeId,
-      srcName,
-      destParentInodeId,
-      destName,
-      { user: this.user }
-    );
-  }
-  async symlink(target, path) {
-    const { parentInodeId, name } = await this.resolveParent(path);
-    await this.client.create(
-      parentInodeId,
-      name,
-      {
-        inodeType: "Symlink",
-        uid: this.user?.uid ?? 0,
-        gid: this.user?.gid ?? 0,
-        mode: 511,
-        symlinkTarget: target
-      },
-      { user: this.user }
-    );
-  }
-  async link(existingPath, newPath) {
-    throw new Error(
-      "Hard link operations not yet implemented. The archil-node bindings need to expose link for hard links."
-    );
-  }
-  async chmod(path, mode) {
-    const { inodeId } = await this.resolveFollow(path);
-    await this.client.setattr(inodeId, { mode }, { user: this.user ?? { uid: 0, gid: 0 } });
-  }
-  async utimes(path, atime, mtime) {
-    debug("utimes path=%s atime=%s mtime=%s", path, atime.toISOString(), mtime.toISOString());
-    const { inodeId } = await this.resolveFollow(path);
-    debug("utimes resolved path=%s inodeId=%d", path, inodeId);
-    const atimeMs = atime.getTime();
-    const mtimeMs = mtime.getTime();
-    debug("utimes calling setattr inodeId=%d atimeMs=%d mtimeMs=%d", inodeId, atimeMs, mtimeMs);
-    await this.client.setattr(
-      inodeId,
-      { atimeMs, mtimeMs },
-      { user: this.user ?? { uid: 0, gid: 0 } }
-    );
-    debug("utimes setattr succeeded inodeId=%d", inodeId);
-  }
-  // ========================================================================
-  // Utility Methods
-  // ========================================================================
-  getAllPaths() {
-    return [];
-  }
-  /**
-   * Resolve a path to its inode ID (public wrapper for delegation operations)
-   */
-  async resolveInodeId(path) {
-    const { inodeId } = await this.resolve(path);
-    return inodeId;
-  }
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let debug = require("debug");
+debug = __toESM(debug, 1);
+let _archildata_native = require("@archildata/native");
+let just_bash = require("just-bash");
+//#region src/ArchilFs.ts
+/**
+* Archil filesystem adapter for just-bash
+*
+* Implements the IFileSystem interface from just-bash using the ArchilClient
+* from @archildata/native for direct protocol access to Archil distributed filesystems.
+*/
+const debug$1 = (0, debug.default)("archil:fs");
+/**
+* ArchilFs implements the just-bash IFileSystem interface using Archil protocol.
+*
+* This adapter provides:
+* - Path-to-inode resolution
+* - Full filesystem operations via Archil protocol
+* - Optional user context for permission checks
+*
+* @example
+* ```typescript
+* import { ArchilClient } from '@archildata/native';
+* import { ArchilFs } from '@archildata/just-bash';
+*
+* const client = await ArchilClient.connect({
+*   region: 'aws-us-east-1',
+*   diskName: 'myaccount/mydisk',
+*   authToken: 'adt_xxx',
+* });
+*
+* const fs = await ArchilFs.create(client);
+*
+* // Use with just-bash
+* import { Bash } from 'just-bash';
+* const bash = new Bash({ fs });
+* await bash.run('ls -la /');
+* ```
+*/
+var ArchilFs = class ArchilFs {
+	client;
+	user;
+	rootInodeId = 1;
+	constructor(client, options) {
+		this.client = client;
+		this.user = options?.user;
+	}
+	/**
+	* Create an ArchilFs adapter, optionally rooted at a subdirectory.
+	*
+	* The subdirectory path is resolved eagerly: if any component does not
+	* exist or is not a directory, this method throws immediately.
+	*
+	* @param client - Connected ArchilClient instance
+	* @param options - Optional configuration
+	* @param options.user - Unix user context for permission checks
+	* @param options.subdirectory - Subdirectory to treat as the root of the filesystem
+	*/
+	static async create(client, options) {
+		const fs = new ArchilFs(client, { user: options?.user });
+		if (options?.subdirectory) {
+			const resolved = await fs.resolveFollow(options.subdirectory);
+			if (resolved.attributes.inodeType !== "Directory") throw new Error(`ENOTDIR: subdirectory '${options.subdirectory}' is not a directory`);
+			fs.rootInodeId = resolved.inodeId;
+			debug$1("resolved subdirectory '%s' to inode %d", options.subdirectory, fs.rootInodeId);
+		}
+		return fs;
+	}
+	/**
+	* Normalize a path (remove . and .., ensure leading /)
+	*/
+	normalizePath(path) {
+		if (!path || path === "") return "/";
+		if (!path.startsWith("/")) path = "/" + path;
+		const parts = path.split("/").filter((p) => p !== "" && p !== ".");
+		const result = [];
+		for (const part of parts) if (part === "..") result.pop();
+		else result.push(part);
+		return "/" + result.join("/");
+	}
+	static MAX_SYMLINKS = 40;
+	/**
+	* Resolve a path to its inode ID, walking the directory tree.
+	* Follows symlinks on intermediate components but NOT on the final
+	* component (matching lstat/readlink semantics).
+	*/
+	async resolve(path, symlinkDepth = 0) {
+		const parts = this.normalizePath(path).split("/").filter((p) => p !== "");
+		let currentInodeId = this.rootInodeId;
+		let resolvedPath = "/";
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			const response = await this.client.lookupInode(currentInodeId, part, { user: this.user });
+			if (response === null) throw new Error(`ENOENT: no such file or directory, '${path}'`);
+			if (!(i === parts.length - 1) && response.attributes.inodeType === "Symlink" && response.attributes.symlinkTarget) {
+				if (symlinkDepth >= ArchilFs.MAX_SYMLINKS) throw new Error(`ELOOP: too many levels of symbolic links, '${path}'`);
+				const targetPath = response.attributes.symlinkTarget.startsWith("/") ? response.attributes.symlinkTarget : this.resolvePath(resolvedPath, response.attributes.symlinkTarget);
+				const remaining = parts.slice(i + 1).join("/");
+				const fullPath = remaining ? targetPath + "/" + remaining : targetPath;
+				return this.resolve(fullPath, symlinkDepth + 1);
+			}
+			resolvedPath = resolvedPath === "/" ? "/" + part : resolvedPath + "/" + part;
+			currentInodeId = response.inodeId;
+		}
+		const attributes = await this.client.getAttributes(currentInodeId, { user: this.user });
+		return {
+			inodeId: currentInodeId,
+			attributes
+		};
+	}
+	/**
+	* Resolve a path, following symlinks on ALL components including the
+	* final one (like stat(2)). Use resolve() when you need lstat semantics.
+	*/
+	async resolveFollow(path, symlinkDepth = 0) {
+		if (symlinkDepth >= ArchilFs.MAX_SYMLINKS) throw new Error(`ELOOP: too many levels of symbolic links, '${path}'`);
+		const resolved = await this.resolve(path, symlinkDepth);
+		if (resolved.attributes.inodeType === "Symlink" && resolved.attributes.symlinkTarget) {
+			const targetPath = resolved.attributes.symlinkTarget.startsWith("/") ? resolved.attributes.symlinkTarget : this.resolvePath(path, "..", resolved.attributes.symlinkTarget);
+			return this.resolveFollow(targetPath, symlinkDepth + 1);
+		}
+		return resolved;
+	}
+	/**
+	* Resolve parent directory and get child name
+	*/
+	async resolveParent(path) {
+		debug$1("resolveParent raw path=%j (bytes: %o)", path, Buffer.from(path));
+		const normalizedPath = this.normalizePath(path);
+		const lastSlash = normalizedPath.lastIndexOf("/");
+		const parentPath = lastSlash === 0 ? "/" : normalizedPath.substring(0, lastSlash);
+		const name = normalizedPath.substring(lastSlash + 1);
+		debug$1("resolveParent extracted name=%j (bytes: %o)", name, Buffer.from(name));
+		const { inodeId: parentInodeId } = await this.resolve(parentPath);
+		return {
+			parentInodeId,
+			name
+		};
+	}
+	/**
+	* Convert InodeAttributes to FsStat
+	*/
+	toStat(attrs) {
+		return {
+			isFile: attrs.inodeType === "File",
+			isDirectory: attrs.inodeType === "Directory",
+			isSymbolicLink: attrs.inodeType === "Symlink",
+			mode: attrs.mode,
+			size: Number(attrs.size),
+			mtime: new Date(attrs.mtimeMs)
+		};
+	}
+	static DIR_PAGE_SIZE = 1e3;
+	/**
+	* Read all directory entries using the paginated API.
+	*/
+	async readAllDirectoryEntries(inodeId) {
+		const handle = await this.client.openDirectory(inodeId, { user: this.user });
+		try {
+			const allEntries = [];
+			let cursor;
+			for (;;) {
+				const page = await this.client.readDirectory(inodeId, handle, ArchilFs.DIR_PAGE_SIZE, cursor, { user: this.user });
+				allEntries.push(...page.entries);
+				if (!page.nextCursor) break;
+				cursor = page.nextCursor;
+			}
+			return allEntries;
+		} finally {
+			this.client.closeDirectory(inodeId, handle);
+		}
+	}
+	resolvePath(base, ...paths) {
+		debug$1("resolvePath base=%s paths=%o", base, paths);
+		let result = base;
+		for (const p of paths) if (p.startsWith("/")) result = p;
+		else result = result.endsWith("/") ? result + p : result + "/" + p;
+		const normalized = this.normalizePath(result);
+		debug$1("resolvePath result=%s", normalized);
+		return normalized;
+	}
+	async readFile(path, encoding) {
+		debug$1("readFile path=%s encoding=%s", path, encoding);
+		try {
+			const buffer = await this.readFileBuffer(path);
+			debug$1("readFile got buffer length=%d", buffer.length);
+			const enc = encoding || "utf-8";
+			let result;
+			if (enc === "base64" || enc === "hex" || enc === "binary") result = Buffer.from(buffer).toString(enc);
+			else result = new TextDecoder(enc).decode(buffer);
+			debug$1("readFile decoded to string length=%d", result.length);
+			return result;
+		} catch (err) {
+			debug$1("readFile FAILED: %O", err);
+			throw err;
+		}
+	}
+	async readFileBuffer(path) {
+		debug$1("readFileBuffer path=%s", path);
+		const { inodeId, attributes } = await this.resolveFollow(path);
+		debug$1("readFileBuffer resolved inodeId=%d type=%s size=%d", inodeId, attributes.inodeType, attributes.size);
+		if (attributes.inodeType !== "File") throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
+		const size = Number(attributes.size);
+		if (size === 0) {
+			debug$1("readFileBuffer file is empty, returning empty buffer");
+			return /* @__PURE__ */ new Uint8Array(0);
+		}
+		if (size <= _archildata_native.MAXIMUM_READ_SIZE) {
+			const buffer = await this.client.readInode(inodeId, 0, size, { user: this.user });
+			return new Uint8Array(buffer);
+		}
+		const result = new Uint8Array(size);
+		let offset = 0;
+		while (offset < size) {
+			const chunkSize = Math.min(_archildata_native.MAXIMUM_READ_SIZE, size - offset);
+			const chunk = await this.client.readInode(inodeId, offset, chunkSize, { user: this.user });
+			result.set(new Uint8Array(chunk), offset);
+			offset += chunkSize;
+		}
+		return result;
+	}
+	async readdir(path) {
+		debug$1("readdir path=%s", path);
+		const { inodeId, attributes } = await this.resolveFollow(path);
+		if (attributes.inodeType !== "Directory") throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
+		const entries = await this.readAllDirectoryEntries(inodeId);
+		for (const e of entries) debug$1("readdir entry name=%j (bytes: %o)", e.name, Buffer.from(e.name));
+		return entries.map((e) => e.name).filter((name) => name !== "." && name !== "..");
+	}
+	async readdirWithFileTypes(path) {
+		const { inodeId, attributes } = await this.resolveFollow(path);
+		if (attributes.inodeType !== "Directory") throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
+		return (await this.readAllDirectoryEntries(inodeId)).filter((e) => e.name !== "." && e.name !== "..").map((e) => ({
+			name: e.name,
+			isFile: e.inodeType === "File",
+			isDirectory: e.inodeType === "Directory",
+			isSymbolicLink: e.inodeType === "Symlink"
+		}));
+	}
+	async stat(path) {
+		debug$1("stat path=%s", path);
+		const { attributes } = await this.resolveFollow(path);
+		return this.toStat(attributes);
+	}
+	async lstat(path) {
+		debug$1("lstat path=%s", path);
+		const { attributes } = await this.resolve(path);
+		return this.toStat(attributes);
+	}
+	async exists(path) {
+		debug$1("exists path=%s", path);
+		try {
+			await this.resolve(path);
+			debug$1("exists path=%s -> true", path);
+			return true;
+		} catch {
+			debug$1("exists path=%s -> false", path);
+			return false;
+		}
+	}
+	async readlink(path) {
+		const { attributes } = await this.resolve(path);
+		if (attributes.inodeType !== "Symlink") throw new Error(`EINVAL: invalid argument, readlink '${path}'`);
+		return attributes.symlinkTarget || "";
+	}
+	async realpath(path, symlinkDepth = 0) {
+		const parts = this.normalizePath(path).split("/").filter((p) => p !== "");
+		let resolvedPath = "/";
+		let currentInodeId = this.rootInodeId;
+		for (const part of parts) {
+			const response = await this.client.lookupInode(currentInodeId, part, { user: this.user });
+			if (response === null) throw new Error(`ENOENT: no such file or directory, realpath '${path}'`);
+			const attrs = response.attributes;
+			if (attrs.inodeType === "Symlink" && attrs.symlinkTarget) {
+				if (symlinkDepth >= ArchilFs.MAX_SYMLINKS) throw new Error(`ELOOP: too many levels of symbolic links, '${path}'`);
+				const targetPath = attrs.symlinkTarget.startsWith("/") ? attrs.symlinkTarget : this.resolvePath(resolvedPath, attrs.symlinkTarget);
+				const resolved = await this.realpath(targetPath, symlinkDepth + 1);
+				resolvedPath = resolved;
+				const { inodeId } = await this.resolve(resolved);
+				currentInodeId = inodeId;
+			} else {
+				resolvedPath = resolvedPath === "/" ? "/" + part : resolvedPath + "/" + part;
+				currentInodeId = response.inodeId;
+			}
+		}
+		return resolvedPath;
+	}
+	async writeFile(path, content) {
+		debug$1("writeFile path=%s contentLength=%d", path, content.length);
+		const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+		let resolved;
+		try {
+			resolved = await this.resolveFollow(path);
+		} catch (err) {
+			if (err instanceof Error && err.message.includes("ENOENT")) resolved = null;
+			else throw err;
+		}
+		if (resolved !== null) {
+			debug$1("writeFile resolved existing file path=%s inodeId=%d", path, resolved.inodeId);
+			if (resolved.attributes.inodeType !== "File") throw new Error(`EISDIR: illegal operation on a directory, write '${path}'`);
+			const realPath = await this.realpath(path);
+			const { parentInodeId, name } = await this.resolveParent(realPath);
+			const tmpName = `.~tmp-${Math.random().toString(36).slice(2)}`;
+			debug$1("writeFile atomic overwrite via temp=%s", tmpName);
+			const tmpResult = await this.client.create(parentInodeId, tmpName, {
+				inodeType: "File",
+				uid: resolved.attributes.uid,
+				gid: resolved.attributes.gid,
+				mode: resolved.attributes.mode
+			}, { user: this.user });
+			try {
+				await this.client.writeData(tmpResult.inodeId, 0, Buffer.from(data), { user: this.user });
+				await this.client.rename(parentInodeId, tmpName, parentInodeId, name, { user: this.user });
+				debug$1("writeFile atomic overwrite succeeded");
+			} catch (writeErr) {
+				try {
+					await this.client.unlink(parentInodeId, tmpName, { user: this.user });
+				} catch {}
+				throw writeErr;
+			}
+			return;
+		}
+		debug$1("writeFile file doesn't exist, creating: %s", path);
+		const { parentInodeId, name } = await this.resolveParent(path);
+		debug$1("writeFile resolved parent parentInodeId=%d name=%s", parentInodeId, name);
+		const result = await this.client.create(parentInodeId, name, {
+			inodeType: "File",
+			uid: this.user?.uid ?? 0,
+			gid: this.user?.gid ?? 0,
+			mode: 420
+		}, { user: this.user });
+		debug$1("writeFile create succeeded inodeId=%d", result.inodeId);
+		await this.client.writeData(result.inodeId, 0, Buffer.from(data), { user: this.user });
+		debug$1("writeFile write succeeded");
+	}
+	async appendFile(path, content) {
+		const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+		let inodeId;
+		let size;
+		try {
+			const resolved = await this.resolveFollow(path);
+			if (resolved.attributes.inodeType !== "File") throw new Error(`EISDIR: illegal operation on a directory, write '${path}'`);
+			inodeId = resolved.inodeId;
+			size = Number(resolved.attributes.size);
+		} catch (err) {
+			if (err instanceof Error && err.message.includes("ENOENT")) {
+				await this.writeFile(path, data);
+				return;
+			}
+			throw err;
+		}
+		await this.client.writeData(inodeId, size, Buffer.from(data), { user: this.user });
+	}
+	async mkdir(path, options) {
+		const normalizedPath = this.normalizePath(path);
+		if (options?.recursive) {
+			const parts = normalizedPath.split("/").filter((p) => p !== "");
+			let currentPath = "";
+			for (const part of parts) {
+				currentPath += "/" + part;
+				if (await this.exists(currentPath)) continue;
+				await this.mkdirSingle(currentPath);
+			}
+		} else await this.mkdirSingle(normalizedPath);
+	}
+	async mkdirSingle(path) {
+		const { parentInodeId, name } = await this.resolveParent(path);
+		await this.client.create(parentInodeId, name, {
+			inodeType: "Directory",
+			uid: this.user?.uid ?? 0,
+			gid: this.user?.gid ?? 0,
+			mode: 493
+		}, { user: this.user });
+	}
+	async rm(path, options) {
+		let resolved;
+		try {
+			resolved = await this.resolve(path);
+		} catch (err) {
+			if (err instanceof Error && err.message.includes("ENOENT")) {
+				if (options?.force) return;
+				throw err;
+			}
+			throw err;
+		}
+		if (resolved.attributes.inodeType === "Directory") {
+			if (!options?.recursive) throw new Error(`EISDIR: illegal operation on a directory, rm '${path}'`);
+			const entries = await this.readdir(path);
+			for (const entry of entries) await this.rm(this.resolvePath(path, entry), options);
+		}
+		const { parentInodeId, name } = await this.resolveParent(path);
+		await this.client.unlink(parentInodeId, name, { user: this.user });
+	}
+	async cp(src, dest, options) {
+		if ((await this.resolveFollow(src)).attributes.inodeType === "Directory") {
+			if (!options?.recursive) throw new Error(`EISDIR: illegal operation on a directory, cp '${src}'`);
+			await this.mkdir(dest, { recursive: true });
+			const entries = await this.readdir(src);
+			for (const entry of entries) await this.cp(this.resolvePath(src, entry), this.resolvePath(dest, entry), options);
+		} else {
+			const content = await this.readFileBuffer(src);
+			await this.writeFile(dest, content);
+		}
+	}
+	async mv(src, dest) {
+		const { parentInodeId: srcParentInodeId, name: srcName } = await this.resolveParent(src);
+		const { parentInodeId: destParentInodeId, name: destName } = await this.resolveParent(dest);
+		await this.client.rename(srcParentInodeId, srcName, destParentInodeId, destName, { user: this.user });
+	}
+	async symlink(target, path) {
+		const { parentInodeId, name } = await this.resolveParent(path);
+		await this.client.create(parentInodeId, name, {
+			inodeType: "Symlink",
+			uid: this.user?.uid ?? 0,
+			gid: this.user?.gid ?? 0,
+			mode: 511,
+			symlinkTarget: target
+		}, { user: this.user });
+	}
+	async link(existingPath, newPath) {
+		throw new Error("Hard link operations not yet implemented. The archil-node bindings need to expose link for hard links.");
+	}
+	async chmod(path, mode) {
+		const { inodeId } = await this.resolveFollow(path);
+		await this.client.setattr(inodeId, { mode }, { user: this.user ?? {
+			uid: 0,
+			gid: 0
+		} });
+	}
+	async utimes(path, atime, mtime) {
+		debug$1("utimes path=%s atime=%s mtime=%s", path, atime.toISOString(), mtime.toISOString());
+		const { inodeId } = await this.resolveFollow(path);
+		debug$1("utimes resolved path=%s inodeId=%d", path, inodeId);
+		const atimeMs = atime.getTime();
+		const mtimeMs = mtime.getTime();
+		debug$1("utimes calling setattr inodeId=%d atimeMs=%d mtimeMs=%d", inodeId, atimeMs, mtimeMs);
+		await this.client.setattr(inodeId, {
+			atimeMs,
+			mtimeMs
+		}, { user: this.user ?? {
+			uid: 0,
+			gid: 0
+		} });
+		debug$1("utimes setattr succeeded inodeId=%d", inodeId);
+	}
+	getAllPaths() {
+		return [];
+	}
+	/**
+	* Resolve a path to its inode ID (public wrapper for delegation operations)
+	*/
+	async resolveInodeId(path) {
+		const { inodeId } = await this.resolve(path);
+		return inodeId;
+	}
 };
-
-// src/commands.ts
-var import_just_bash = require("just-bash");
+//#endregion
+//#region src/commands.ts
+/**
+* Create the `archil` custom command for use with just-bash.
+*
+* Provides checkout/checkin delegation management, delegation listing, and
+* cache control (invalidate-cache, set-cache-expiry) as a shell command that
+* works in scripts, pipes, and interactive use.
+*
+* @example
+* ```typescript
+* import { Bash } from 'just-bash';
+* import { ArchilFs, createArchilCommand } from '@archildata/just-bash';
+*
+* const fs = await ArchilFs.create(client);
+* const bash = new Bash({
+*   fs,
+*   customCommands: [createArchilCommand(client, fs)],
+* });
+*
+* await bash.exec('archil checkout /mydir');
+* await bash.exec('echo "hello" > /mydir/file.txt');
+* await bash.exec('archil checkin /mydir');
+* ```
+*/
 function createArchilCommand(client, fs) {
-  return (0, import_just_bash.defineCommand)("archil", async (args, ctx) => {
-    const ok = (stdout) => ({ stdout, stderr: "", exitCode: 0 });
-    const fail = (stderr) => ({ stdout: "", stderr, exitCode: 1 });
-    const subcommand = args[0];
-    if (subcommand === "checkout") {
-      const rest = args.slice(1);
-      const force = rest.includes("--force") || rest.includes("-f");
-      const pathArg = rest.find((a) => !a.startsWith("-"));
-      if (!pathArg) {
-        return fail("Usage: archil checkout [--force|-f] <path>\n");
-      }
-      const fullPath = fs.resolvePath(ctx.cwd, pathArg);
-      try {
-        const inodeId = await fs.resolveInodeId(fullPath);
-        await client.checkout(inodeId, { force });
-        return ok(`Checked out: ${fullPath} (inode ${inodeId})${force ? " (forced)" : ""}
-`);
-      } catch (err) {
-        return fail(`Failed to checkout ${fullPath}: ${err instanceof Error ? err.message : err}
-`);
-      }
-    }
-    if (subcommand === "checkin") {
-      const pathArg = args[1];
-      if (!pathArg) {
-        return fail("Usage: archil checkin <path>\n");
-      }
-      const fullPath = fs.resolvePath(ctx.cwd, pathArg);
-      try {
-        const inodeId = await fs.resolveInodeId(fullPath);
-        await client.checkin(inodeId);
-        return ok(`Checked in: ${fullPath} (inode ${inodeId})
-`);
-      } catch (err) {
-        return fail(`Failed to checkin ${fullPath}: ${err instanceof Error ? err.message : err}
-`);
-      }
-    }
-    if (subcommand === "list-delegations" || subcommand === "delegations") {
-      try {
-        const delegations = client.listDelegations();
-        if (delegations.length === 0) {
-          return ok("No delegations held\n");
-        }
-        const lines = delegations.map((d) => `  inode ${d.inodeId}: ${d.state}`);
-        return ok("Delegations:\n" + lines.join("\n") + "\n");
-      } catch (err) {
-        return fail(`Failed to list delegations: ${err instanceof Error ? err.message : err}
-`);
-      }
-    }
-    if (subcommand === "invalidate-cache") {
-      const pathArg = args.slice(1).find((a) => !a.startsWith("-"));
-      let scopeLabel = "(mount-wide)";
-      if (pathArg) {
-        const fullPath = fs.resolvePath(ctx.cwd, pathArg);
-        try {
-          await fs.resolveInodeId(fullPath);
-          scopeLabel = `(via ${fullPath})`;
-        } catch (err) {
-          return fail(`Failed to resolve ${fullPath}: ${err instanceof Error ? err.message : err}
-`);
-        }
-      }
-      try {
-        const stats = client.invalidateCache();
-        return ok(
-          `Invalidated cache ${scopeLabel}: ${stats.totalEvictedInodes} inodes evicted (attr=${stats.attribute}, xattr=${stats.extendedAttribute}, dirent=${stats.dirent}, file=${stats.fileData})
-`
-        );
-      } catch (err) {
-        return fail(`Failed to invalidate cache: ${err instanceof Error ? err.message : err}
-`);
-      }
-    }
-    if (subcommand === "set-cache-expiry") {
-      const rest = args.slice(1);
-      const flagIdx = rest.indexOf("--readdir-expiry");
-      if (flagIdx === -1 || flagIdx === rest.length - 1) {
-        return fail("Usage: archil set-cache-expiry <path> --readdir-expiry <seconds>\n");
-      }
-      const flagValueIdx = flagIdx + 1;
-      const expirySeconds = Number(rest[flagValueIdx]);
-      if (!Number.isInteger(expirySeconds) || expirySeconds < 0) {
-        return fail("--readdir-expiry must be a non-negative integer (seconds)\n");
-      }
-      const pathArg = rest.find((a, i) => i !== flagIdx && i !== flagValueIdx && !a.startsWith("-"));
-      if (!pathArg) {
-        return fail("Usage: archil set-cache-expiry <path> --readdir-expiry <seconds>\n");
-      }
-      const fullPath = fs.resolvePath(ctx.cwd, pathArg);
-      try {
-        const inodeId = await fs.resolveInodeId(fullPath);
-        client.setCacheExpiry(inodeId, expirySeconds);
-        return ok(`Set readdir cache expiry for ${fullPath} (inode ${inodeId}) to ${expirySeconds}s
-`);
-      } catch (err) {
-        return fail(`Failed to set cache expiry for ${fullPath}: ${err instanceof Error ? err.message : err}
-`);
-      }
-    }
-    if (subcommand === "help" || !subcommand) {
-      return ok(
-        "Archil commands:\n  archil checkout [--force|-f] <path>             - Acquire write delegation\n  archil checkin <path>                           - Release write delegation\n  archil list-delegations                         - Show held delegations\n  archil invalidate-cache [<path>]                - Drop every evictable cache entry\n  archil set-cache-expiry <path> --readdir-expiry <secs>\n                                                  - Set readdir cache TTL on a directory\n  archil help                                     - Show this help message\n\nThe --force flag revokes any existing delegation from other clients.\n"
-      );
-    }
-    return fail(`Unknown archil command: ${subcommand}
-Run 'archil help' for available commands
-`);
-  });
+	return (0, just_bash.defineCommand)("archil", async (args, ctx) => {
+		const ok = (stdout) => ({
+			stdout,
+			stderr: "",
+			exitCode: 0
+		});
+		const fail = (stderr) => ({
+			stdout: "",
+			stderr,
+			exitCode: 1
+		});
+		const subcommand = args[0];
+		if (subcommand === "checkout") {
+			const rest = args.slice(1);
+			const force = rest.includes("--force") || rest.includes("-f");
+			const pathArg = rest.find((a) => !a.startsWith("-"));
+			if (!pathArg) return fail("Usage: archil checkout [--force|-f] <path>\n");
+			const fullPath = fs.resolvePath(ctx.cwd, pathArg);
+			try {
+				const inodeId = await fs.resolveInodeId(fullPath);
+				await client.checkout(inodeId, { force });
+				return ok(`Checked out: ${fullPath} (inode ${inodeId})${force ? " (forced)" : ""}\n`);
+			} catch (err) {
+				return fail(`Failed to checkout ${fullPath}: ${err instanceof Error ? err.message : err}\n`);
+			}
+		}
+		if (subcommand === "checkin") {
+			const pathArg = args[1];
+			if (!pathArg) return fail("Usage: archil checkin <path>\n");
+			const fullPath = fs.resolvePath(ctx.cwd, pathArg);
+			try {
+				const inodeId = await fs.resolveInodeId(fullPath);
+				await client.checkin(inodeId);
+				return ok(`Checked in: ${fullPath} (inode ${inodeId})\n`);
+			} catch (err) {
+				return fail(`Failed to checkin ${fullPath}: ${err instanceof Error ? err.message : err}\n`);
+			}
+		}
+		if (subcommand === "list-delegations" || subcommand === "delegations") try {
+			const delegations = client.listDelegations();
+			if (delegations.length === 0) return ok("No delegations held\n");
+			return ok("Delegations:\n" + delegations.map((d) => `  inode ${d.inodeId}: ${d.state}`).join("\n") + "\n");
+		} catch (err) {
+			return fail(`Failed to list delegations: ${err instanceof Error ? err.message : err}\n`);
+		}
+		if (subcommand === "invalidate-cache") {
+			const pathArg = args.slice(1).find((a) => !a.startsWith("-"));
+			let scopeLabel = "(mount-wide)";
+			if (pathArg) {
+				const fullPath = fs.resolvePath(ctx.cwd, pathArg);
+				try {
+					await fs.resolveInodeId(fullPath);
+					scopeLabel = `(via ${fullPath})`;
+				} catch (err) {
+					return fail(`Failed to resolve ${fullPath}: ${err instanceof Error ? err.message : err}\n`);
+				}
+			}
+			try {
+				const stats = client.invalidateCache();
+				return ok(`Invalidated cache ${scopeLabel}: ${stats.totalEvictedInodes} inodes evicted (attr=${stats.attribute}, xattr=${stats.extendedAttribute}, dirent=${stats.dirent}, file=${stats.fileData})\n`);
+			} catch (err) {
+				return fail(`Failed to invalidate cache: ${err instanceof Error ? err.message : err}\n`);
+			}
+		}
+		if (subcommand === "set-cache-expiry") {
+			const rest = args.slice(1);
+			const flagIdx = rest.indexOf("--readdir-expiry");
+			if (flagIdx === -1 || flagIdx === rest.length - 1) return fail("Usage: archil set-cache-expiry <path> --readdir-expiry <seconds>\n");
+			const flagValueIdx = flagIdx + 1;
+			const expirySeconds = Number(rest[flagValueIdx]);
+			if (!Number.isInteger(expirySeconds) || expirySeconds < 0) return fail("--readdir-expiry must be a non-negative integer (seconds)\n");
+			const pathArg = rest.find((a, i) => i !== flagIdx && i !== flagValueIdx && !a.startsWith("-"));
+			if (!pathArg) return fail("Usage: archil set-cache-expiry <path> --readdir-expiry <seconds>\n");
+			const fullPath = fs.resolvePath(ctx.cwd, pathArg);
+			try {
+				const inodeId = await fs.resolveInodeId(fullPath);
+				client.setCacheExpiry(inodeId, expirySeconds);
+				return ok(`Set readdir cache expiry for ${fullPath} (inode ${inodeId}) to ${expirySeconds}s\n`);
+			} catch (err) {
+				return fail(`Failed to set cache expiry for ${fullPath}: ${err instanceof Error ? err.message : err}\n`);
+			}
+		}
+		if (subcommand === "help" || !subcommand) return ok("Archil commands:\n  archil checkout [--force|-f] <path>             - Acquire write delegation\n  archil checkin <path>                           - Release write delegation\n  archil list-delegations                         - Show held delegations\n  archil invalidate-cache [<path>]                - Drop every evictable cache entry\n  archil set-cache-expiry <path> --readdir-expiry <secs>\n                                                  - Set readdir cache TTL on a directory\n  archil help                                     - Show this help message\n\nThe --force flag revokes any existing delegation from other clients.\n");
+		return fail(`Unknown archil command: ${subcommand}\nRun 'archil help' for available commands\n`);
+	});
 }
-
-// src/index.ts
+//#endregion
+//#region src/index.ts
+/**
+* @archildata/just-bash - Archil filesystem adapter for just-bash
+*
+* This package provides a filesystem adapter that allows just-bash to use
+* Archil distributed filesystems as a backend.
+*
+* @example
+* ```typescript
+* import { ArchilClient } from '@archildata/native';
+* 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',
+* });
+*
+* // Create filesystem adapter
+* const fs = await ArchilFs.create(client);
+*
+* // Use with just-bash
+* const bash = new Bash({ fs });
+* const result = await bash.run('ls -la /');
+* console.log(result.stdout);
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Create an ArchilFs instance, optionally rooted at a subdirectory.
+*
+* @param client - Connected ArchilClient instance
+* @param options - Optional configuration
+* @returns Configured ArchilFs instance
+*
+* @example
+* ```typescript
+* import { ArchilClient } from '@archildata/native';
+* import { createArchilFs } from '@archildata/just-bash';
+*
+* const client = await ArchilClient.connectAuthenticated({...});
+* const fs = await createArchilFs(client, { user: { uid: 1000, gid: 1000 } });
+* ```
+*/
 async function createArchilFs(client, options) {
-  return ArchilFs.create(client, options);
+	return ArchilFs.create(client, options);
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ArchilFs,
-  createArchilCommand,
-  createArchilFs
-});
+//#endregion
+exports.ArchilFs = ArchilFs;
+exports.createArchilCommand = createArchilCommand;
+exports.createArchilFs = createArchilFs;