just-bash-dropbox 0.1.0 → 0.2.0

package/README.md

@@ -107,21 +107,37 @@ rm -r /path/dir                   # delete directory
 mkdir -p /path/deep/nested        # create nested directories
 ```
 
+### Semantic notes
+
+- `lstat` delegates to `stat` (Dropbox has no symlinks)
+- `realpath` verifies the path exists and returns Dropbox's canonical casing
+- `rm /dir` (without `-r`) throws `EISDIR` — matches POSIX behavior
+- `>>` (append) uses optimistic locking via Dropbox's `rev` field to detect concurrent writes
+
 ### Not supported
 
-Dropbox doesn't have these concepts. These operations throw `ENOSYS`:
+These operations throw `ENOSYS`:
 
 - `chmod` — no file permissions
 - `ln` / `ln -s` — no hard/symbolic links
-- `readlink`, `realpath` — no symlinks to resolve
+- `readlink` — no symlinks
+- `utimes` — Dropbox manages timestamps
+
+### Glob support
+
+`getAllPaths()` returns `[]` by default (sync method can't make API calls). For glob support, call `prefetchAllPaths()` first:
+
+```ts
+await fs.prefetchAllPaths(); // recursive listing, cached
+fs.getAllPaths(); // returns all paths
+```
 
 ### Limitations
 
 - **File size**: Single uploads are limited to 150 MB
-- **Append**: `>>` works but downloads the entire file, appends, and re-uploads
+- **Append**: `>>` downloads the file, appends, re-uploads with rev-based conflict detection
 - **Case sensitivity**: Dropbox paths are case-insensitive (`/README.md` and `/readme.md` are the same file)
 - **Rate limits**: Handled automatically with retry + backoff; heavy usage may still hit Dropbox's per-user limits
-- **No glob via `getAllPaths`**: Returns `[]` — glob matching works through `readdir` + `stat` instead
 
 ## Error handling
 
@@ -134,6 +150,9 @@ Errors are mapped to errno-style codes for natural bash output:
 | `path/not_file` | `EISDIR` | Expected file, got directory |
 | `path/not_folder` | `ENOTDIR` | Expected directory, got file |
 | `insufficient_quota` | `ENOSPC` | Dropbox quota exceeded |
+| HTTP 401 | `EACCES` | Token expired or invalid |
+| HTTP 403 | `EACCES` | Insufficient app permissions |
+| `rm /dir` (no `-r`) | `EISDIR` | Use `rm -r` to delete directories |
 
 ```ts
 import { FsError } from "just-bash-dropbox";

package/dist/dropbox-fs.d.ts

@@ -1,38 +1,21 @@
+import type { CpOptions, FileContent, FsStat, MkdirOptions, RmOptions } from "just-bash";
 import type { DropboxFsOptions } from "./types.js";
-interface FsStat {
-    isFile: boolean;
-    isDirectory: boolean;
-    isSymbolicLink: boolean;
-    mode: number;
-    size: number;
-    mtime: Date;
-}
 interface DirentEntry {
     name: string;
     isFile: boolean;
     isDirectory: boolean;
     isSymbolicLink: boolean;
 }
-interface MkdirOptions {
-    recursive?: boolean;
-}
-interface RmOptions {
-    recursive?: boolean;
-    force?: boolean;
-}
-interface CpOptions {
-    recursive?: boolean;
-}
 interface ReadFileOptions {
     encoding?: string | null;
 }
 interface WriteFileOptions {
     encoding?: string;
 }
-type FileContent = string | Uint8Array;
 export declare class DropboxFs {
     private readonly client;
     private readonly rootPath;
+    private cachedPaths;
     constructor(options: DropboxFsOptions);
     readdir(path: string): Promise<string[]>;
     readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
@@ -48,12 +31,18 @@ export declare class DropboxFs {
     mv(src: string, dest: string): Promise<void>;
     resolvePath(base: string, target: string): string;
     getAllPaths(): string[];
+    /**
+     * Prefetch all file and folder paths via recursive list_folder.
+     * Call this before operations that need getAllPaths() (like glob).
+     * Results are cached until the next call to prefetchAllPaths().
+     */
+    prefetchAllPaths(): Promise<string[]>;
     chmod(_path: string, _mode: number): Promise<void>;
     symlink(_target: string, _linkPath: string): Promise<void>;
     link(_existingPath: string, _newPath: string): Promise<void>;
     readlink(_path: string): Promise<string>;
-    lstat(_path: string): Promise<FsStat>;
-    realpath(_path: string): Promise<string>;
+    lstat(path: string): Promise<FsStat>;
+    realpath(path: string): Promise<string>;
     utimes(_path: string, _atime: Date, _mtime: Date): Promise<void>;
     private toPath;
     private listFolder;

package/dist/dropbox-fs.js

@@ -1,9 +1,10 @@
 import { DropboxApiError, DropboxClient } from "./dropbox-client.js";
-import { enosys, FsError, mapDropboxError } from "./errors.js";
+import { eisdir, enosys, FsError, mapDropboxError } from "./errors.js";
 import { resolvePath as resolvePathUtil, toDropboxPath } from "./paths.js";
 export class DropboxFs {
     client;
     rootPath;
+    cachedPaths = [];
     constructor(options) {
         this.client = new DropboxClient({
             accessToken: options.accessToken,
@@ -94,23 +95,40 @@ export class DropboxFs {
         }
     }
     async appendFile(path, content, _options) {
+        const dbxPath = this.toPath(path);
+        // Download existing file with metadata (to get rev for optimistic locking)
         let existing;
+        let rev;
         try {
-            existing = await this.readFileBuffer(path);
+            const result = await this.client.contentDownload("/2/files/download", {
+                path: dbxPath,
+            });
+            existing = result.content;
+            rev = result.metadata.rev;
         }
         catch (err) {
-            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            if (err instanceof DropboxApiError &&
+                err.errorSummary.startsWith("path/not_found")) {
                 // File doesn't exist — create it
                 await this.writeFile(path, content);
                 return;
             }
-            throw err;
+            throw mapDropboxError(err, path);
         }
         const appendBytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
         const combined = new Uint8Array(existing.length + appendBytes.length);
         combined.set(existing, 0);
         combined.set(appendBytes, existing.length);
-        await this.writeFile(path, combined);
+        // Upload with rev-based optimistic locking to detect concurrent writes
+        const mode = rev
+            ? { ".tag": "update", update: rev }
+            : "overwrite";
+        try {
+            await this.client.contentUpload("/2/files/upload", { path: dbxPath, mode, autorename: false, mute: true }, combined);
+        }
+        catch (err) {
+            throw mapDropboxError(err, path);
+        }
     }
     async mkdir(path, options) {
         const dbxPath = this.toPath(path);
@@ -127,6 +145,20 @@ export class DropboxFs {
     }
     async rm(path, options) {
         const dbxPath = this.toPath(path);
+        // POSIX: rm without -r on a directory should fail
+        if (!options?.recursive) {
+            try {
+                const s = await this.stat(path);
+                if (s.isDirectory) {
+                    throw eisdir(path);
+                }
+            }
+            catch (err) {
+                if (err instanceof FsError && err.code === "EISDIR")
+                    throw err;
+                // If stat fails (e.g. ENOENT), let delete_v2 handle it below
+            }
+        }
         try {
             await this.client.rpc("/2/files/delete_v2", { path: dbxPath });
         }
@@ -170,7 +202,33 @@ export class DropboxFs {
         return resolvePathUtil(base, target);
     }
     getAllPaths() {
-        return [];
+        return this.cachedPaths;
+    }
+    /**
+     * Prefetch all file and folder paths via recursive list_folder.
+     * Call this before operations that need getAllPaths() (like glob).
+     * Results are cached until the next call to prefetchAllPaths().
+     */
+    async prefetchAllPaths() {
+        const dbxPath = this.toPath("/");
+        const allPaths = [];
+        try {
+            let result = await this.client.rpc("/2/files/list_folder", { path: dbxPath, recursive: true, include_deleted: false });
+            for (const entry of result.entries) {
+                allPaths.push(entry.path_display);
+            }
+            while (result.has_more) {
+                result = await this.client.rpc("/2/files/list_folder/continue", { cursor: result.cursor });
+                for (const entry of result.entries) {
+                    allPaths.push(entry.path_display);
+                }
+            }
+        }
+        catch (err) {
+            throw mapDropboxError(err, "/");
+        }
+        this.cachedPaths = allPaths;
+        return allPaths;
     }
     // ─── Unsupported operations ─────────────────────────
     async chmod(_path, _mode) {
@@ -185,11 +243,24 @@ export class DropboxFs {
     async readlink(_path) {
         throw enosys("readlink");
     }
-    async lstat(_path) {
-        throw enosys("lstat");
+    async lstat(path) {
+        // Dropbox has no symlinks — lstat is identical to stat
+        return this.stat(path);
     }
-    async realpath(_path) {
-        throw enosys("realpath");
+    async realpath(path) {
+        const dbxPath = this.toPath(path);
+        // Root has no metadata endpoint
+        if (dbxPath === "" || dbxPath === "/") {
+            return "/";
+        }
+        try {
+            const metadata = await this.client.rpc("/2/files/get_metadata", { path: dbxPath });
+            // Return canonical casing from Dropbox
+            return metadata.path_display;
+        }
+        catch (err) {
+            throw mapDropboxError(err, path);
+        }
     }
     async utimes(_path, _atime, _mtime) {
         throw enosys("utimes");
@@ -251,7 +322,7 @@ function metadataToStat(metadata) {
                 isSymbolicLink: false,
                 mode: 0o755,
                 size: 0,
-                mtime: new Date(),
+                mtime: new Date(0),
             };
         case "deleted":
             throw new FsError("ENOENT", "no such file or directory (deleted)");

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-export { DropboxApiError, DropboxClient } from "./dropbox-client.js";
 export { DropboxFs } from "./dropbox-fs.js";
 export { FsError } from "./errors.js";
-export type { DropboxFileMetadata, DropboxFolderMetadata, DropboxFsOptions, DropboxMetadata, } from "./types.js";
+export type { DropboxFsOptions } from "./types.js";

package/dist/index.js

@@ -1,3 +1,2 @@
-export { DropboxApiError, DropboxClient } from "./dropbox-client.js";
 export { DropboxFs } from "./dropbox-fs.js";
 export { FsError } from "./errors.js";

package/dist/type-check.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/type-check.js

@@ -0,0 +1,4 @@
+// Fails to compile if DropboxFs drifts from IFileSystem
+const _check = {};
+void _check;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "just-bash-dropbox",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Dropbox filesystem adapter for just-bash",
   "repository": {
     "type": "git",
@@ -49,6 +49,7 @@
     "@biomejs/biome": "^2.3.10",
     "@types/node": "^22.0.0",
     "typescript": "^5.9.3",
+    "just-bash": "^2.14.0",
     "vitest": "^4.0.16"
   },
   "peerDependencies": {