@archildata/just-bash 0.1.13 → 0.8.1

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import * as _archildata_client from '@archildata/client';
 import { ArchilClient, UnixUser } from '@archildata/client';
+import * as just_bash from 'just-bash';
 
 /**
  * Archil filesystem adapter for just-bash
@@ -13,7 +14,7 @@ type FileContent = string | Uint8Array;
 interface FsStat {
     isFile: boolean;
     isDirectory: boolean;
-    isSymlink: boolean;
+    isSymbolicLink: boolean;
     mode: number;
     size: number;
     mtime: Date;
@@ -22,7 +23,7 @@ interface DirentEntry {
     name: string;
     isFile: boolean;
     isDirectory: boolean;
-    isSymlink: boolean;
+    isSymbolicLink: boolean;
 }
 interface IFileSystem {
     readFile(path: string, encoding?: BufferEncoding): Promise<string>;
@@ -50,9 +51,9 @@ interface IFileSystem {
     symlink(target: string, path: string): Promise<void>;
     link(existingPath: string, newPath: string): Promise<void>;
     chmod(path: string, mode: number): Promise<void>;
-    utimes(path: string, atime: number, mtime: number): Promise<void>;
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
     resolvePath(base: string, ...paths: string[]): string;
-    getAllPaths?(): Promise<string[]>;
+    getAllPaths?(): string[];
 }
 /**
  * ArchilFs implements the just-bash IFileSystem interface using Archil protocol.
@@ -73,7 +74,7 @@ interface IFileSystem {
  *   authToken: 'adt_xxx',
  * });
  *
- * const fs = new ArchilFs(client);
+ * const fs = await ArchilFs.create(client);
  *
  * // Use with just-bash
  * import { Bash } from 'just-bash';
@@ -85,24 +86,38 @@ declare class ArchilFs implements IFileSystem {
     private client;
     private user?;
     private rootInodeId;
+    private constructor();
     /**
-     * Create a new ArchilFs adapter
+     * 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
      */
-    constructor(client: ArchilClient, options?: {
+    static create(client: ArchilClient, options?: {
         user?: UnixUser;
-    });
+        subdirectory?: string;
+    }): Promise<ArchilFs>;
     /**
      * Normalize a path (remove . and .., ensure leading /)
      */
     private normalizePath;
+    private static readonly MAX_SYMLINKS;
     /**
-     * Resolve a path to its inode ID, walking the directory tree
+     * 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).
      */
     private resolve;
+    /**
+     * Resolve a path, following symlinks on ALL components including the
+     * final one (like stat(2)). Use resolve() when you need lstat semantics.
+     */
+    private resolveFollow;
     /**
      * Resolve parent directory and get child name
      */
@@ -111,6 +126,11 @@ declare class ArchilFs implements IFileSystem {
      * Convert InodeAttributes to FsStat
      */
     private toStat;
+    private static readonly DIR_PAGE_SIZE;
+    /**
+     * Read all directory entries using the paginated API.
+     */
+    private readAllDirectoryEntries;
     resolvePath(base: string, ...paths: string[]): string;
     readFile(path: string, encoding?: BufferEncoding): Promise<string>;
     readFileBuffer(path: string): Promise<Uint8Array>;
@@ -120,7 +140,7 @@ declare class ArchilFs implements IFileSystem {
     lstat(path: string): Promise<FsStat>;
     exists(path: string): Promise<boolean>;
     readlink(path: string): Promise<string>;
-    realpath(path: string): Promise<string>;
+    realpath(path: string, symlinkDepth?: number): Promise<string>;
     writeFile(path: string, content: FileContent): Promise<void>;
     appendFile(path: string, content: FileContent): Promise<void>;
     mkdir(path: string, options?: {
@@ -138,8 +158,8 @@ declare class ArchilFs implements IFileSystem {
     symlink(target: string, path: string): Promise<void>;
     link(existingPath: string, newPath: string): Promise<void>;
     chmod(path: string, mode: number): Promise<void>;
-    utimes(path: string, atime: number, mtime: number): Promise<void>;
-    getAllPaths(): Promise<string[]>;
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
+    getAllPaths(): string[];
     /**
      * Resolve a path to its inode ID (public wrapper for delegation operations)
      */
@@ -147,9 +167,31 @@ declare class ArchilFs implements IFileSystem {
 }
 
 /**
- * Create an ArchilFs instance from an existing client
+ * Create the `archil` custom command for use with just-bash.
+ *
+ * Provides checkout/checkin delegation management and delegation listing
+ * as a shell command that works in scripts, pipes, and interactive use.
  *
- * This is a convenience function for creating the filesystem adapter.
+ * @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');
+ * ```
+ */
+declare function createArchilCommand(client: ArchilClient, fs: ArchilFs): just_bash.Command;
+
+/**
+ * Create an ArchilFs instance, optionally rooted at a subdirectory.
  *
  * @param client - Connected ArchilClient instance
  * @param options - Optional configuration
@@ -161,11 +203,12 @@ declare class ArchilFs implements IFileSystem {
  * import { createArchilFs } from '@archildata/just-bash';
  *
  * const client = await ArchilClient.connectAuthenticated({...});
- * const fs = createArchilFs(client, { user: { uid: 1000, gid: 1000 } });
+ * const fs = await createArchilFs(client, { user: { uid: 1000, gid: 1000 } });
  * ```
  */
 declare function createArchilFs(client: _archildata_client.ArchilClient, options?: {
     user?: _archildata_client.UnixUser;
-}): ArchilFs;
+    subdirectory?: string;
+}): Promise<ArchilFs>;
 
-export { ArchilFs, type BufferEncoding, type DirentEntry, type FileContent, type FsStat, type IFileSystem, createArchilFs };
+export { ArchilFs, type BufferEncoding, type DirentEntry, type FileContent, type FsStat, type IFileSystem, createArchilCommand, createArchilFs };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _archildata_client from '@archildata/client';
 import { ArchilClient, UnixUser } from '@archildata/client';
+import * as just_bash from 'just-bash';
 
 /**
  * Archil filesystem adapter for just-bash
@@ -13,7 +14,7 @@ type FileContent = string | Uint8Array;
 interface FsStat {
     isFile: boolean;
     isDirectory: boolean;
-    isSymlink: boolean;
+    isSymbolicLink: boolean;
     mode: number;
     size: number;
     mtime: Date;
@@ -22,7 +23,7 @@ interface DirentEntry {
     name: string;
     isFile: boolean;
     isDirectory: boolean;
-    isSymlink: boolean;
+    isSymbolicLink: boolean;
 }
 interface IFileSystem {
     readFile(path: string, encoding?: BufferEncoding): Promise<string>;
@@ -50,9 +51,9 @@ interface IFileSystem {
     symlink(target: string, path: string): Promise<void>;
     link(existingPath: string, newPath: string): Promise<void>;
     chmod(path: string, mode: number): Promise<void>;
-    utimes(path: string, atime: number, mtime: number): Promise<void>;
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
     resolvePath(base: string, ...paths: string[]): string;
-    getAllPaths?(): Promise<string[]>;
+    getAllPaths?(): string[];
 }
 /**
  * ArchilFs implements the just-bash IFileSystem interface using Archil protocol.
@@ -73,7 +74,7 @@ interface IFileSystem {
  *   authToken: 'adt_xxx',
  * });
  *
- * const fs = new ArchilFs(client);
+ * const fs = await ArchilFs.create(client);
  *
  * // Use with just-bash
  * import { Bash } from 'just-bash';
@@ -85,24 +86,38 @@ declare class ArchilFs implements IFileSystem {
     private client;
     private user?;
     private rootInodeId;
+    private constructor();
     /**
-     * Create a new ArchilFs adapter
+     * 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
      */
-    constructor(client: ArchilClient, options?: {
+    static create(client: ArchilClient, options?: {
         user?: UnixUser;
-    });
+        subdirectory?: string;
+    }): Promise<ArchilFs>;
     /**
      * Normalize a path (remove . and .., ensure leading /)
      */
     private normalizePath;
+    private static readonly MAX_SYMLINKS;
     /**
-     * Resolve a path to its inode ID, walking the directory tree
+     * 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).
      */
     private resolve;
+    /**
+     * Resolve a path, following symlinks on ALL components including the
+     * final one (like stat(2)). Use resolve() when you need lstat semantics.
+     */
+    private resolveFollow;
     /**
      * Resolve parent directory and get child name
      */
@@ -111,6 +126,11 @@ declare class ArchilFs implements IFileSystem {
      * Convert InodeAttributes to FsStat
      */
     private toStat;
+    private static readonly DIR_PAGE_SIZE;
+    /**
+     * Read all directory entries using the paginated API.
+     */
+    private readAllDirectoryEntries;
     resolvePath(base: string, ...paths: string[]): string;
     readFile(path: string, encoding?: BufferEncoding): Promise<string>;
     readFileBuffer(path: string): Promise<Uint8Array>;
@@ -120,7 +140,7 @@ declare class ArchilFs implements IFileSystem {
     lstat(path: string): Promise<FsStat>;
     exists(path: string): Promise<boolean>;
     readlink(path: string): Promise<string>;
-    realpath(path: string): Promise<string>;
+    realpath(path: string, symlinkDepth?: number): Promise<string>;
     writeFile(path: string, content: FileContent): Promise<void>;
     appendFile(path: string, content: FileContent): Promise<void>;
     mkdir(path: string, options?: {
@@ -138,8 +158,8 @@ declare class ArchilFs implements IFileSystem {
     symlink(target: string, path: string): Promise<void>;
     link(existingPath: string, newPath: string): Promise<void>;
     chmod(path: string, mode: number): Promise<void>;
-    utimes(path: string, atime: number, mtime: number): Promise<void>;
-    getAllPaths(): Promise<string[]>;
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
+    getAllPaths(): string[];
     /**
      * Resolve a path to its inode ID (public wrapper for delegation operations)
      */
@@ -147,9 +167,31 @@ declare class ArchilFs implements IFileSystem {
 }
 
 /**
- * Create an ArchilFs instance from an existing client
+ * Create the `archil` custom command for use with just-bash.
+ *
+ * Provides checkout/checkin delegation management and delegation listing
+ * as a shell command that works in scripts, pipes, and interactive use.
  *
- * This is a convenience function for creating the filesystem adapter.
+ * @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');
+ * ```
+ */
+declare function createArchilCommand(client: ArchilClient, fs: ArchilFs): just_bash.Command;
+
+/**
+ * Create an ArchilFs instance, optionally rooted at a subdirectory.
  *
  * @param client - Connected ArchilClient instance
  * @param options - Optional configuration
@@ -161,11 +203,12 @@ declare class ArchilFs implements IFileSystem {
  * import { createArchilFs } from '@archildata/just-bash';
  *
  * const client = await ArchilClient.connectAuthenticated({...});
- * const fs = createArchilFs(client, { user: { uid: 1000, gid: 1000 } });
+ * const fs = await createArchilFs(client, { user: { uid: 1000, gid: 1000 } });
  * ```
  */
 declare function createArchilFs(client: _archildata_client.ArchilClient, options?: {
     user?: _archildata_client.UnixUser;
-}): ArchilFs;
+    subdirectory?: string;
+}): Promise<ArchilFs>;
 
-export { ArchilFs, type BufferEncoding, type DirentEntry, type FileContent, type FsStat, type IFileSystem, createArchilFs };
+export { ArchilFs, type BufferEncoding, type DirentEntry, type FileContent, type FsStat, type IFileSystem, createArchilCommand, createArchilFs };