@archildata/just-bash 0.1.13 → 0.8.1

package/dist/index.js

@@ -1,510 +1,602 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-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;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
 // src/ArchilFs.ts
-var ArchilFs_exports = {};
-__export(ArchilFs_exports, {
-  ArchilFs: () => ArchilFs
-});
 import createDebug from "debug";
-var debug, ArchilFs;
-var init_ArchilFs = __esm({
-  "src/ArchilFs.ts"() {
-    "use strict";
-    debug = createDebug("archil:fs");
-    ArchilFs = class {
-      client;
-      user;
-      rootInodeId = 1;
-      /**
-       * Create a new ArchilFs adapter
-       *
-       * @param client - Connected ArchilClient instance
-       * @param options - Optional configuration
-       * @param options.user - Unix user context for permission checks
-       */
-      constructor(client, options) {
-        this.client = client;
-        this.user = options?.user;
-      }
-      // ========================================================================
-      // 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("/");
-      }
-      /**
-       * Resolve a path to its inode ID, walking the directory tree
-       */
-      async resolve(path) {
-        const normalizedPath = this.normalizePath(path);
-        const parts = normalizedPath.split("/").filter((p) => p !== "");
-        let currentInodeId = this.rootInodeId;
-        for (const part of parts) {
-          const response = await this.client.lookupInode(currentInodeId, part, { user: this.user });
-          if (response.inodeId === -1) {
-            throw new Error(`ENOENT: no such file or directory, '${path}'`);
-          }
-          currentInodeId = response.inodeId;
-        }
-        const attributes = await this.client.getAttributes(currentInodeId, { user: this.user });
-        return { inodeId: currentInodeId, attributes };
+var debug = createDebug("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`);
       }
-      /**
-       * 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 };
+      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);
       }
-      /**
-       * Convert InodeAttributes to FsStat
-       */
-      toStat(attrs) {
-        return {
-          isFile: attrs.inodeType === "File",
-          isDirectory: attrs.inodeType === "Directory",
-          isSymlink: attrs.inodeType === "Symlink",
-          mode: attrs.mode,
-          size: Number(attrs.size),
-          mtime: new Date(attrs.mtimeMs)
-        };
+    }
+    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}'`);
       }
-      // ========================================================================
-      // 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 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 normalized = this.normalizePath(result);
-        debug("resolvePath result=%s", normalized);
-        return normalized;
+        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);
       }
-      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 decoderEncoding = encoding === "binary" ? "latin1" : encoding || "utf-8";
-          debug("readFile using decoder encoding=%s", decoderEncoding);
-          const decoder = new TextDecoder(decoderEncoding);
-          const result = decoder.decode(buffer);
-          debug("readFile decoded to string length=%d", result.length);
-          return result;
-        } catch (err) {
-          debug("readFile FAILED: %O", err);
-          throw err;
-        }
+      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;
       }
-      async readFileBuffer(path) {
-        debug("readFileBuffer path=%s", path);
-        const { inodeId, attributes } = await this.resolve(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);
-        }
-        const MAX_CHUNK = 4 * 1024 * 1024;
-        if (size <= MAX_CHUNK) {
-          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(MAX_CHUNK, size - offset);
-          const chunk = await this.client.readInode(inodeId, offset, chunkSize, { user: this.user });
-          result.set(new Uint8Array(chunk), offset);
-          offset += chunkSize;
-        }
-        return result;
+      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;
       }
-      async readdir(path) {
-        debug("readdir path=%s", path);
-        const { inodeId, attributes } = await this.resolve(path);
-        if (attributes.inodeType !== "Directory") {
-          throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
-        }
-        const entries = await this.client.readDirectory(inodeId, { user: this.user });
-        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 !== "..");
+    }
+    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);
       }
-      async readdirWithFileTypes(path) {
-        const { inodeId, attributes } = await this.resolve(path);
-        if (attributes.inodeType !== "Directory") {
-          throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
-        }
-        const entries = await this.client.readDirectory(inodeId, { user: this.user });
-        return entries.filter((e) => e.name !== "." && e.name !== "..").map((e) => ({
-          name: e.name,
-          isFile: e.inodeType === "File",
-          isDirectory: e.inodeType === "Directory",
-          isSymlink: e.inodeType === "Symlink"
-        }));
+      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);
+    }
+    const MAX_CHUNK = 4 * 1024 * 1024;
+    if (size <= MAX_CHUNK) {
+      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(MAX_CHUNK, 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}'`);
       }
-      async stat(path) {
-        debug("stat path=%s", path);
-        const { attributes } = await this.resolve(path);
-        if (attributes.inodeType === "Symlink" && attributes.symlinkTarget) {
-          const targetPath = attributes.symlinkTarget.startsWith("/") ? attributes.symlinkTarget : this.resolvePath(path, "..", attributes.symlinkTarget);
-          return this.stat(targetPath);
+      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}'`);
         }
-        return this.toStat(attributes);
+        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;
       }
-      async lstat(path) {
-        debug("lstat path=%s", path);
-        const { attributes } = await this.resolve(path);
-        return this.toStat(attributes);
+    }
+    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;
       }
-      async exists(path) {
-        debug("exists path=%s", path);
+    }
+    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.resolve(path);
-          debug("exists path=%s -> true", path);
-          return true;
+          await this.client.unlink(parentInodeId2, tmpName, { user: this.user });
         } catch {
-          debug("exists path=%s -> false", path);
-          return false;
         }
+        throw writeErr;
       }
-      async readlink(path) {
-        const { attributes } = await this.resolve(path);
-        if (attributes.inodeType !== "Symlink") {
-          throw new Error(`EINVAL: invalid argument, readlink '${path}'`);
-        }
-        return attributes.symlinkTarget || "";
+      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}'`);
       }
-      async realpath(path) {
-        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.inodeId === -1) {
-            throw new Error(`ENOENT: no such file or directory, realpath '${path}'`);
-          }
-          const attrs = response.attributes;
-          if (attrs.inodeType === "Symlink" && attrs.symlinkTarget) {
-            const targetPath = attrs.symlinkTarget.startsWith("/") ? attrs.symlinkTarget : this.resolvePath(resolvedPath, attrs.symlinkTarget);
-            const resolved = await this.realpath(targetPath);
-            resolvedPath = resolved;
-            const { inodeId } = await this.resolve(resolved);
-            currentInodeId = inodeId;
-          } else {
-            resolvedPath = resolvedPath === "/" ? "/" + part : resolvedPath + "/" + part;
-            currentInodeId = response.inodeId;
-          }
-        }
-        return resolvedPath;
+      inodeId = resolved.inodeId;
+      size = Number(resolved.attributes.size);
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("ENOENT")) {
+        await this.writeFile(path, data);
+        return;
       }
-      // ========================================================================
-      // 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 inodeId;
-        try {
-          const resolved = await this.resolve(path);
-          inodeId = resolved.inodeId;
-          debug("writeFile resolved existing file path=%s inodeId=%d", path, inodeId);
-          if (resolved.attributes.inodeType !== "File") {
-            throw new Error(`EISDIR: illegal operation on a directory, write '${path}'`);
-          }
-        } catch (err) {
-          if (err instanceof Error && err.message.includes("EISDIR")) {
-            throw err;
-          }
-          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 now = Date.now();
-          debug("writeFile calling create parent=%d name=%s", parentInodeId, name);
-          try {
-            inodeId = await this.client.create(
-              parentInodeId,
-              name,
-              {
-                inodeId: 0,
-                // Will be assigned by the filesystem
-                inodeType: "File",
-                size: 0,
-                uid: this.user?.uid ?? 0,
-                gid: this.user?.gid ?? 0,
-                mode: 420,
-                nlink: 1,
-                ctimeMs: now,
-                atimeMs: now,
-                mtimeMs: now,
-                btimeMs: now,
-                rdev: void 0,
-                symlinkTarget: void 0
-              },
-              { user: this.user }
-            );
-            debug("writeFile create succeeded inodeId=%d", inodeId);
-          } catch (createErr) {
-            debug("writeFile create FAILED: %O", createErr);
-            throw createErr;
-          }
-        }
-        debug("writeFile writing %d bytes to inodeId=%d", data.length, inodeId);
-        await this.client.writeData(inodeId, 0, Buffer.from(data), { user: this.user });
-        debug("writeFile write succeeded");
-      }
-      async appendFile(path, content) {
-        let existing;
-        try {
-          existing = await this.readFileBuffer(path);
-        } catch {
-          existing = new Uint8Array(0);
+      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;
         }
-        const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
-        const combined = new Uint8Array(existing.length + data.length);
-        combined.set(existing, 0);
-        combined.set(data, existing.length);
-        await this.writeFile(path, combined);
+        await this.mkdirSingle(currentPath);
       }
-      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);
+    } 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;
       }
-      async mkdirSingle(path) {
-        const { parentInodeId, name } = await this.resolveParent(path);
-        const now = Date.now();
-        await this.client.create(
-          parentInodeId,
-          name,
-          {
-            inodeId: 0,
-            // Will be assigned by the filesystem
-            inodeType: "Directory",
-            size: 4096,
-            uid: this.user?.uid ?? 0,
-            gid: this.user?.gid ?? 0,
-            mode: 493,
-            nlink: 2,
-            ctimeMs: now,
-            atimeMs: now,
-            mtimeMs: now,
-            btimeMs: now,
-            rdev: void 0,
-            symlinkTarget: void 0
-          },
-          { user: this.user }
-        );
-      }
-      async rm(path, options) {
-        let resolved;
-        try {
-          resolved = await this.resolve(path);
-        } catch {
-          if (options?.force) {
-            return;
-          }
-          throw new Error(`ENOENT: no such file or directory, rm '${path}'`);
-        }
-        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 });
+      throw err;
+    }
+    if (resolved.attributes.inodeType === "Directory") {
+      if (!options?.recursive) {
+        throw new Error(`EISDIR: illegal operation on a directory, rm '${path}'`);
       }
-      async cp(src, dest, options) {
-        const srcResolved = await this.resolve(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);
-        }
+      const entries = await this.readdir(path);
+      for (const entry of entries) {
+        await this.rm(this.resolvePath(path, entry), options);
       }
-      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 }
-        );
+    }
+    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}'`);
       }
-      async symlink(target, path) {
-        const { parentInodeId, name } = await this.resolveParent(path);
-        const now = Date.now();
-        await this.client.create(
-          parentInodeId,
-          name,
-          {
-            inodeId: 0,
-            // Will be assigned by the filesystem
-            inodeType: "Symlink",
-            size: target.length,
-            uid: this.user?.uid ?? 0,
-            gid: this.user?.gid ?? 0,
-            mode: 511,
-            nlink: 1,
-            ctimeMs: now,
-            atimeMs: now,
-            mtimeMs: now,
-            btimeMs: now,
-            rdev: void 0,
-            symlinkTarget: target
-          },
-          { user: this.user }
+      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
         );
       }
-      async link(existingPath, newPath) {
-        throw new Error(
-          "Hard link operations not yet implemented. The archil-node bindings need to expose link for hard links."
-        );
+    } 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;
+  }
+};
+
+// src/commands.ts
+import { defineCommand } from "just-bash";
+function createArchilCommand(client, fs) {
+  return 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");
       }
-      async chmod(path, mode) {
-        const { inodeId } = await this.resolve(path);
-        await this.client.setattr(inodeId, { mode }, { user: this.user ?? { uid: 0, gid: 0 } });
+      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}
+`);
       }
-      async utimes(path, atime, mtime) {
-        debug("utimes path=%s atime=%d mtime=%d", path, atime, mtime);
-        const { inodeId } = await this.resolve(path);
-        debug("utimes resolved path=%s inodeId=%d", path, inodeId);
-        const atimeMs = atime === -1 ? -1 : Math.floor(atime * 1e3);
-        const mtimeMs = mtime === -1 ? -1 : Math.floor(mtime * 1e3);
-        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);
+    }
+    if (subcommand === "checkin") {
+      const pathArg = args[1];
+      if (!pathArg) {
+        return fail("Usage: archil checkin <path>\n");
       }
-      // ========================================================================
-      // Utility Methods
-      // ========================================================================
-      async getAllPaths() {
-        const paths = [];
-        const walk = async (dirPath) => {
-          paths.push(dirPath);
-          try {
-            const entries = await this.readdirWithFileTypes(dirPath);
-            for (const entry of entries) {
-              const fullPath = this.resolvePath(dirPath, entry.name);
-              if (entry.isDirectory) {
-                await walk(fullPath);
-              } else {
-                paths.push(fullPath);
-              }
-            }
-          } catch {
-          }
-        };
-        await walk("/");
-        return paths;
+      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}
+`);
       }
-      /**
-       * Resolve a path to its inode ID (public wrapper for delegation operations)
-       */
-      async resolveInodeId(path) {
-        const { inodeId } = await this.resolve(path);
-        return inodeId;
+    }
+    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 === "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 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
+`);
+  });
+}
 
 // src/index.ts
-init_ArchilFs();
-function createArchilFs(client, options) {
-  const { ArchilFs: ArchilFs2 } = (init_ArchilFs(), __toCommonJS(ArchilFs_exports));
-  return new ArchilFs2(client, options);
+async function createArchilFs(client, options) {
+  return ArchilFs.create(client, options);
 }
 export {
   ArchilFs,
+  createArchilCommand,
   createArchilFs
 };