just-bash-dropbox 0.1.0

package/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md - just-bash-dropbox
+
+Instructions for AI agents using just-bash-dropbox in projects.
+
+## What is just-bash-dropbox?
+
+A Dropbox filesystem adapter for [just-bash](https://github.com/vercel-labs/just-bash). It implements the `IFileSystem` interface so you can access Dropbox files through bash commands — `ls`, `cat`, `grep`, `awk`, and everything else just-bash supports.
+
+## Quick Reference
+
+```typescript
+import { Bash } from "just-bash";
+import { DropboxFs } from "just-bash-dropbox";
+
+const fs = new DropboxFs({ accessToken: process.env.DROPBOX_TOKEN });
+const bash = new Bash({ fs });
+
+const result = await bash.exec("cat /Documents/report.csv | head -5");
+// result.stdout  - file content
+// result.stderr  - error output
+// result.exitCode - 0 = success
+```
+
+## Key Behaviors
+
+1. **Every operation is an API call**: `readdir`, `stat`, `readFile` each hit the Dropbox API. There is no local cache. For repeated reads, wrap with `OverlayFs`.
+
+2. **Paths are case-insensitive**: `/README.md` and `/readme.md` are the same file. This matches Dropbox behavior.
+
+3. **Write operations are real**: `echo "x" > /file` uploads to Dropbox. Use `MountableFs` for safe, memory-only writes.
+
+4. **Token expiry**: Access tokens expire after ~4 hours. Use `getAccessToken` for long sessions.
+
+5. **Rate limits**: Automatically retried with backoff. Avoid tight loops over large directories.
+
+## Safe Mode
+
+**Recommended for untrusted code.** Mount Dropbox at a path, writes go to in-memory base:
+
+```typescript
+import { Bash, MountableFs } from "just-bash";
+import { DropboxFs } from "just-bash-dropbox";
+
+const dropbox = new DropboxFs({ accessToken: "..." });
+const mfs = new MountableFs();
+mfs.mount("/dropbox", dropbox);
+const bash = new Bash({ fs: mfs });
+// reads /dropbox/* from Dropbox, writes anywhere else go to memory
+```
+
+## Scoping
+
+Restrict access to a subfolder:
+
+```typescript
+const fs = new DropboxFs({
+  accessToken: "...",
+  rootPath: "/work/project-x",
+});
+// Agent sees "/" but can only access /work/project-x and below
+```
+
+## Unsupported Operations
+
+These throw `ENOSYS` — Dropbox doesn't support them:
+
+- `chmod`, `ln`, `ln -s`, `readlink`, `realpath`
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| `ENOENT` | File/directory not found |
+| `EEXIST` | Already exists |
+| `EISDIR` | Is a directory (expected file) |
+| `ENOTDIR` | Not a directory (expected directory) |
+| `ENOSPC` | Dropbox quota exceeded |
+| `ENOSYS` | Operation not supported |
+
+## Limitations
+
+- Single uploads: 150 MB max
+- `>>` (append): downloads, appends, re-uploads — slow for large files
+- `getAllPaths()` returns `[]` — glob works via readdir + stat

package/README.md

@@ -0,0 +1,188 @@
+# just-bash-dropbox
+
+> **Beta** — API may change. Use at your own risk.
+
+A Dropbox filesystem adapter for [just-bash](https://github.com/vercel-labs/just-bash). Lets AI agents access Dropbox files through bash commands.
+
+```ts
+import { Bash } from "just-bash";
+import { DropboxFs } from "just-bash-dropbox";
+
+const fs = new DropboxFs({ accessToken: process.env.DROPBOX_TOKEN });
+const bash = new Bash({ fs });
+
+const { stdout } = await bash.exec("ls /Documents");
+// "report.csv\nphotos\n"
+
+await bash.exec("cat /reports/q4-summary.md");
+await bash.exec("grep 'revenue' /reports/*.csv | sort -t, -k2 -rn");
+```
+
+## Install
+
+```bash
+npm install just-bash-dropbox just-bash
+```
+
+No other dependencies. Uses native `fetch` — Node 18+.
+
+## Authentication
+
+`DropboxFs` needs a Dropbox access token. Provide it directly or via a function that returns a fresh token.
+
+```ts
+// Static token — scripts, testing, short-lived sessions
+const fs = new DropboxFs({ accessToken: "sl...." });
+
+// Token provider — production, long-running agents
+// Called before each API request. You handle refresh and persistence.
+const fs = new DropboxFs({
+  getAccessToken: async () => {
+    return await myTokenStore.getFreshToken(userId);
+  },
+});
+```
+
+Get a token: create a Dropbox app at [dropbox.com/developers](https://www.dropbox.com/developers) and generate an access token, or implement the [OAuth2 flow](https://www.dropbox.com/developers/documentation/http/documentation#authorization).
+
+Access tokens expire after ~4 hours. For agents that run longer, use `getAccessToken` with a refresh token flow (see `examples/token-provider.ts`).
+
+## Scoping to a folder
+
+Restrict the filesystem to a Dropbox subfolder. The agent sees `/` but operations are scoped underneath. Use this to limit what an agent can access.
+
+```ts
+const fs = new DropboxFs({
+  accessToken: "...",
+  rootPath: "/work/project-x",
+});
+
+const bash = new Bash({ fs });
+await bash.exec("ls /");          // lists /work/project-x
+await bash.exec("cat /readme.md"); // reads /work/project-x/readme.md
+```
+
+## Safe mode (read-only mount)
+
+Use just-bash's `MountableFs` to mount Dropbox at a path while keeping the rest in memory. Writes go to the in-memory base filesystem, not to Dropbox. **Recommended for untrusted agents.**
+
+```ts
+import { Bash, MountableFs } from "just-bash";
+import { DropboxFs } from "just-bash-dropbox";
+
+const dropbox = new DropboxFs({ accessToken: "..." });
+const mfs = new MountableFs();
+mfs.mount("/dropbox", dropbox);
+const bash = new Bash({ fs: mfs });
+
+await bash.exec("cat /dropbox/data.csv");             // reads from Dropbox
+await bash.exec("echo 'hello' > /notes.txt");          // writes to in-memory fs
+await bash.exec("cp /dropbox/data.csv /local-copy.csv"); // copies to memory
+```
+
+## API
+
+### `new DropboxFs(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `accessToken` | `string` | — | Static Dropbox access token |
+| `getAccessToken` | `() => string \| Promise<string>` | — | Returns a fresh token per request |
+| `rootPath` | `string` | `"/"` (root) | Scope all operations to this folder |
+
+Provide either `accessToken` or `getAccessToken`, not both.
+
+### Supported operations
+
+All standard bash file operations work:
+
+```bash
+ls /path                          # list directory
+cat /path/file.txt                # read file
+echo "content" > /path/file.txt   # write file
+cp /src /dest                     # copy
+mv /src /dest                     # move
+rm /path/file.txt                 # delete
+rm -r /path/dir                   # delete directory
+mkdir -p /path/deep/nested        # create nested directories
+```
+
+### Not supported
+
+Dropbox doesn't have these concepts. These operations throw `ENOSYS`:
+
+- `chmod` — no file permissions
+- `ln` / `ln -s` — no hard/symbolic links
+- `readlink`, `realpath` — no symlinks to resolve
+
+### Limitations
+
+- **File size**: Single uploads are limited to 150 MB
+- **Append**: `>>` works but downloads the entire file, appends, and re-uploads
+- **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
+
+Errors are mapped to errno-style codes for natural bash output:
+
+| Dropbox error | Mapped code | Meaning |
+|---------------|-------------|---------|
+| `path/not_found` | `ENOENT` | File or directory doesn't exist |
+| `path/conflict` | `EEXIST` | Already exists |
+| `path/not_file` | `EISDIR` | Expected file, got directory |
+| `path/not_folder` | `ENOTDIR` | Expected directory, got file |
+| `insufficient_quota` | `ENOSPC` | Dropbox quota exceeded |
+
+```ts
+import { FsError } from "just-bash-dropbox";
+
+try {
+  await fs.readFile("/missing.txt");
+} catch (err) {
+  if (err instanceof FsError && err.code === "ENOENT") {
+    // file not found
+  }
+}
+```
+
+## Interactive CLI
+
+Chat with an AI that has full access to your Dropbox:
+
+```bash
+DROPBOX_TOKEN=sl.xxx AI_GATEWAY_API_KEY=xxx npx tsx examples/chat-cli.ts
+```
+
+```
+you: what files do I have?
+  $ ls -la /
+  welcome.md
+
+ai: You have one file — `welcome.md`. Want me to read it?
+
+you: create a project plan in /plan.md
+  $ echo "# Project Plan" > /plan.md
+  $ echo "## Phase 1: Research" >> /plan.md
+
+ai: Created /plan.md with a project plan outline.
+```
+
+See [`examples/chat-cli.ts`](./examples/chat-cli.ts) for the implementation — it's ~100 lines using the Vercel AI SDK.
+
+## Examples
+
+See the [`examples/`](./examples) directory:
+
+- **`chat-cli.ts`** — Interactive CLI chat agent (recommended starting point)
+- **`ai-agent-sdk.ts`** — Single-prompt AI agent with Vercel AI SDK
+- **`safe-mode.ts`** — Read-only mount with `MountableFs`
+- **`token-provider.ts`** — Production auth with auto-refresh
+- **`basic-browsing.ts`** — List and read files
+- **`file-search.ts`** — `grep` and `awk` on Dropbox files
+- **`ai-agent.ts`** — Scripted agent workflow (no LLM)
+
+## License
+
+Apache-2.0

package/dist/dropbox-client.d.ts

@@ -0,0 +1,38 @@
+import type { DropboxFsOptions } from "./types.js";
+export declare class DropboxApiError extends Error {
+    readonly status: number;
+    readonly errorSummary: string;
+    readonly errorBody: unknown;
+    constructor(status: number, errorSummary: string, errorBody: unknown);
+}
+export declare class DropboxClient {
+    private readonly getToken;
+    constructor(options: Pick<DropboxFsOptions, "accessToken" | "getAccessToken">);
+    /**
+     * RPC-style request: JSON in body, JSON response.
+     * Used for list_folder, get_metadata, create_folder, delete, copy, move.
+     */
+    rpc<T>(endpoint: string, args: Record<string, unknown>): Promise<T>;
+    /**
+     * Content-upload: args in Dropbox-API-Arg header, file bytes in body.
+     * Used for upload.
+     */
+    contentUpload<T>(endpoint: string, args: Record<string, unknown>, content: Uint8Array): Promise<T>;
+    /**
+     * Content-download: args in Dropbox-API-Arg header, file bytes in response.
+     * Used for download.
+     */
+    contentDownload(endpoint: string, args: Record<string, unknown>): Promise<{
+        metadata: Record<string, unknown>;
+        content: Uint8Array;
+    }>;
+    /**
+     * Low-level request with retry on 429.
+     * Parses JSON response and throws DropboxApiError on error status.
+     */
+    private request;
+    /**
+     * Raw request with retry logic. Returns the Response object.
+     */
+    private requestRaw;
+}

package/dist/dropbox-client.js

@@ -0,0 +1,126 @@
+const RPC_HOST = "https://api.dropboxapi.com";
+const CONTENT_HOST = "https://content.dropboxapi.com";
+const MAX_RETRIES = 3;
+export class DropboxApiError extends Error {
+    status;
+    errorSummary;
+    errorBody;
+    constructor(status, errorSummary, errorBody) {
+        super(errorSummary);
+        this.status = status;
+        this.errorSummary = errorSummary;
+        this.errorBody = errorBody;
+        this.name = "DropboxApiError";
+    }
+}
+export class DropboxClient {
+    getToken;
+    constructor(options) {
+        if (options.accessToken && options.getAccessToken) {
+            throw new Error("Provide either accessToken or getAccessToken, not both");
+        }
+        if (!options.accessToken && !options.getAccessToken) {
+            throw new Error("Provide either accessToken or getAccessToken");
+        }
+        this.getToken =
+            options.getAccessToken ?? (() => options.accessToken);
+    }
+    /**
+     * RPC-style request: JSON in body, JSON response.
+     * Used for list_folder, get_metadata, create_folder, delete, copy, move.
+     */
+    async rpc(endpoint, args) {
+        return this.request(async (token) => {
+            const response = await fetch(`${RPC_HOST}${endpoint}`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(args),
+            });
+            return response;
+        });
+    }
+    /**
+     * Content-upload: args in Dropbox-API-Arg header, file bytes in body.
+     * Used for upload.
+     */
+    async contentUpload(endpoint, args, content) {
+        return this.request(async (token) => {
+            const response = await fetch(`${CONTENT_HOST}${endpoint}`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/octet-stream",
+                    "Dropbox-API-Arg": JSON.stringify(args),
+                },
+                body: content,
+            });
+            return response;
+        });
+    }
+    /**
+     * Content-download: args in Dropbox-API-Arg header, file bytes in response.
+     * Used for download.
+     */
+    async contentDownload(endpoint, args) {
+        const response = await this.requestRaw(async (token) => {
+            const resp = await fetch(`${CONTENT_HOST}${endpoint}`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Dropbox-API-Arg": JSON.stringify(args),
+                },
+            });
+            return resp;
+        });
+        const resultHeader = response.headers.get("Dropbox-API-Result");
+        const metadata = resultHeader ? JSON.parse(resultHeader) : {};
+        const content = new Uint8Array(await response.arrayBuffer());
+        return { metadata, content };
+    }
+    /**
+     * Low-level request with retry on 429.
+     * Parses JSON response and throws DropboxApiError on error status.
+     */
+    async request(doFetch) {
+        const response = await this.requestRaw(doFetch);
+        return response.json();
+    }
+    /**
+     * Raw request with retry logic. Returns the Response object.
+     */
+    async requestRaw(doFetch) {
+        let lastError;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            const token = await this.getToken();
+            const response = await doFetch(token);
+            if (response.ok) {
+                return response;
+            }
+            if (response.status === 429) {
+                const parsed = Number(response.headers.get("Retry-After"));
+                const retryAfter = Number.isFinite(parsed) ? parsed : 1;
+                // Consume body to avoid leak
+                await response.text();
+                await sleep(retryAfter * 1000);
+                lastError = new Error("Rate limited");
+                continue;
+            }
+            // Parse error body for 409 and other errors
+            const body = await response.json().catch(() => ({}));
+            const summary = typeof body === "object" &&
+                body !== null &&
+                "error_summary" in body &&
+                typeof body.error_summary === "string"
+                ? body.error_summary
+                : `HTTP ${response.status}`;
+            throw new DropboxApiError(response.status, summary, body);
+        }
+        throw lastError ?? new Error("Request failed after retries");
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/dropbox-fs.d.ts

@@ -0,0 +1,62 @@
+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;
+    constructor(options: DropboxFsOptions);
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    readFile(path: string, _options?: ReadFileOptions | string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    stat(path: string): Promise<FsStat>;
+    exists(path: string): Promise<boolean>;
+    writeFile(path: string, content: FileContent, _options?: WriteFileOptions | string): Promise<void>;
+    appendFile(path: string, content: FileContent, _options?: WriteFileOptions | string): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, _options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    resolvePath(base: string, target: string): string;
+    getAllPaths(): 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>;
+    utimes(_path: string, _atime: Date, _mtime: Date): Promise<void>;
+    private toPath;
+    private listFolder;
+    private mkdirRecursive;
+}
+export {};

package/dist/dropbox-fs.js

@@ -0,0 +1,259 @@
+import { DropboxApiError, DropboxClient } from "./dropbox-client.js";
+import { enosys, FsError, mapDropboxError } from "./errors.js";
+import { resolvePath as resolvePathUtil, toDropboxPath } from "./paths.js";
+export class DropboxFs {
+    client;
+    rootPath;
+    constructor(options) {
+        this.client = new DropboxClient({
+            accessToken: options.accessToken,
+            getAccessToken: options.getAccessToken,
+        });
+        this.rootPath = options.rootPath;
+    }
+    // ─── Read operations ────────────────────────────────
+    async readdir(path) {
+        const entries = await this.listFolder(path);
+        return entries.map((e) => e.name);
+    }
+    async readdirWithFileTypes(path) {
+        const entries = await this.listFolder(path);
+        return entries.map((e) => ({
+            name: e.name,
+            isFile: e[".tag"] === "file",
+            isDirectory: e[".tag"] === "folder",
+            isSymbolicLink: false,
+        }));
+    }
+    async readFile(path, _options) {
+        try {
+            const dbxPath = this.toPath(path);
+            const result = await this.client.contentDownload("/2/files/download", {
+                path: dbxPath,
+            });
+            return new TextDecoder().decode(result.content);
+        }
+        catch (err) {
+            throw mapDropboxError(err, path);
+        }
+    }
+    async readFileBuffer(path) {
+        try {
+            const dbxPath = this.toPath(path);
+            const result = await this.client.contentDownload("/2/files/download", {
+                path: dbxPath,
+            });
+            return result.content;
+        }
+        catch (err) {
+            throw mapDropboxError(err, path);
+        }
+    }
+    async stat(path) {
+        const dbxPath = this.toPath(path);
+        // Dropbox API does not support get_metadata on root folder
+        if (dbxPath === "" || dbxPath === "/") {
+            return {
+                isFile: false,
+                isDirectory: true,
+                isSymbolicLink: false,
+                mode: 0o755,
+                size: 0,
+                mtime: new Date(0),
+            };
+        }
+        try {
+            const metadata = await this.client.rpc("/2/files/get_metadata", { path: dbxPath });
+            return metadataToStat(metadata);
+        }
+        catch (err) {
+            throw mapDropboxError(err, path);
+        }
+    }
+    async exists(path) {
+        try {
+            await this.stat(path);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+                return false;
+            }
+            throw err;
+        }
+    }
+    // ─── Write operations ───────────────────────────────
+    async writeFile(path, content, _options) {
+        const dbxPath = this.toPath(path);
+        const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        try {
+            await this.client.contentUpload("/2/files/upload", { path: dbxPath, mode: "overwrite", autorename: false, mute: true }, bytes);
+        }
+        catch (err) {
+            throw mapDropboxError(err, path);
+        }
+    }
+    async appendFile(path, content, _options) {
+        let existing;
+        try {
+            existing = await this.readFileBuffer(path);
+        }
+        catch (err) {
+            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+                // File doesn't exist — create it
+                await this.writeFile(path, content);
+                return;
+            }
+            throw err;
+        }
+        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);
+    }
+    async mkdir(path, options) {
+        const dbxPath = this.toPath(path);
+        if (options?.recursive) {
+            await this.mkdirRecursive(dbxPath, path);
+            return;
+        }
+        try {
+            await this.client.rpc("/2/files/create_folder_v2", { path: dbxPath });
+        }
+        catch (err) {
+            throw mapDropboxError(err, path);
+        }
+    }
+    async rm(path, options) {
+        const dbxPath = this.toPath(path);
+        try {
+            await this.client.rpc("/2/files/delete_v2", { path: dbxPath });
+        }
+        catch (err) {
+            if (options?.force &&
+                err instanceof DropboxApiError &&
+                err.errorSummary.startsWith("path_lookup/not_found")) {
+                return;
+            }
+            throw mapDropboxError(err, path);
+        }
+    }
+    async cp(src, dest, _options) {
+        const fromPath = this.toPath(src);
+        const toPath = this.toPath(dest);
+        try {
+            await this.client.rpc("/2/files/copy_v2", {
+                from_path: fromPath,
+                to_path: toPath,
+            });
+        }
+        catch (err) {
+            throw mapDropboxError(err, src);
+        }
+    }
+    async mv(src, dest) {
+        const fromPath = this.toPath(src);
+        const toPath = this.toPath(dest);
+        try {
+            await this.client.rpc("/2/files/move_v2", {
+                from_path: fromPath,
+                to_path: toPath,
+            });
+        }
+        catch (err) {
+            throw mapDropboxError(err, src);
+        }
+    }
+    // ─── Path operations ───────────────────────────────
+    resolvePath(base, target) {
+        return resolvePathUtil(base, target);
+    }
+    getAllPaths() {
+        return [];
+    }
+    // ─── Unsupported operations ─────────────────────────
+    async chmod(_path, _mode) {
+        throw enosys("chmod");
+    }
+    async symlink(_target, _linkPath) {
+        throw enosys("symlink");
+    }
+    async link(_existingPath, _newPath) {
+        throw enosys("link");
+    }
+    async readlink(_path) {
+        throw enosys("readlink");
+    }
+    async lstat(_path) {
+        throw enosys("lstat");
+    }
+    async realpath(_path) {
+        throw enosys("realpath");
+    }
+    async utimes(_path, _atime, _mtime) {
+        throw enosys("utimes");
+    }
+    // ─── Private helpers ───────────────────────────────
+    toPath(path) {
+        return toDropboxPath(path, this.rootPath);
+    }
+    async listFolder(path) {
+        const dbxPath = this.toPath(path);
+        const allEntries = [];
+        try {
+            let result = await this.client.rpc("/2/files/list_folder", { path: dbxPath, include_deleted: false });
+            allEntries.push(...result.entries);
+            while (result.has_more) {
+                result = await this.client.rpc("/2/files/list_folder/continue", { cursor: result.cursor });
+                allEntries.push(...result.entries);
+            }
+        }
+        catch (err) {
+            throw mapDropboxError(err, path);
+        }
+        return allEntries;
+    }
+    async mkdirRecursive(dbxPath, originalPath) {
+        // Build list of paths to create from root to leaf
+        const parts = dbxPath.split("/").filter(Boolean);
+        for (let i = 1; i <= parts.length; i++) {
+            const segment = `/${parts.slice(0, i).join("/")}`;
+            try {
+                await this.client.rpc("/2/files/create_folder_v2", { path: segment });
+            }
+            catch (err) {
+                // Ignore "already exists" errors during recursive creation
+                if (err instanceof DropboxApiError &&
+                    err.errorSummary.startsWith("path/conflict")) {
+                    continue;
+                }
+                throw mapDropboxError(err, originalPath);
+            }
+        }
+    }
+}
+function metadataToStat(metadata) {
+    switch (metadata[".tag"]) {
+        case "file":
+            return {
+                isFile: true,
+                isDirectory: false,
+                isSymbolicLink: false,
+                mode: 0o644,
+                size: metadata.size,
+                mtime: new Date(metadata.server_modified),
+            };
+        case "folder":
+            return {
+                isFile: false,
+                isDirectory: true,
+                isSymbolicLink: false,
+                mode: 0o755,
+                size: 0,
+                mtime: new Date(),
+            };
+        case "deleted":
+            throw new FsError("ENOENT", "no such file or directory (deleted)");
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Maps Dropbox API errors to filesystem-style errors.
+ * Uses errno-like codes so bash commands produce natural error output.
+ */
+export declare class FsError extends Error {
+    readonly code: string;
+    readonly path?: string | undefined;
+    constructor(code: string, message: string, path?: string | undefined);
+}
+export declare function enoent(path: string): FsError;
+export declare function enotdir(path: string): FsError;
+export declare function eisdir(path: string): FsError;
+export declare function eexist(path: string): FsError;
+export declare function enosys(operation: string): FsError;
+export declare function enospc(path: string): FsError;
+/**
+ * Maps a DropboxApiError to a filesystem error.
+ * Uses error_summary prefix matching as recommended by Dropbox docs.
+ */
+export declare function mapDropboxError(err: unknown, path: string): FsError;

package/dist/errors.js

@@ -0,0 +1,73 @@
+import { DropboxApiError } from "./dropbox-client.js";
+/**
+ * Maps Dropbox API errors to filesystem-style errors.
+ * Uses errno-like codes so bash commands produce natural error output.
+ */
+export class FsError extends Error {
+    code;
+    path;
+    constructor(code, message, path) {
+        super(path ? `${code}: ${message}, '${path}'` : `${code}: ${message}`);
+        this.code = code;
+        this.path = path;
+        this.name = "FsError";
+    }
+}
+export function enoent(path) {
+    return new FsError("ENOENT", "no such file or directory", path);
+}
+export function enotdir(path) {
+    return new FsError("ENOTDIR", "not a directory", path);
+}
+export function eisdir(path) {
+    return new FsError("EISDIR", "is a directory", path);
+}
+export function eexist(path) {
+    return new FsError("EEXIST", "file already exists", path);
+}
+export function enosys(operation) {
+    return new FsError("ENOSYS", `${operation} is not supported on Dropbox`);
+}
+export function enospc(path) {
+    return new FsError("ENOSPC", "no space left (Dropbox quota exceeded)", path);
+}
+/**
+ * Maps a DropboxApiError to a filesystem error.
+ * Uses error_summary prefix matching as recommended by Dropbox docs.
+ */
+export function mapDropboxError(err, path) {
+    if (!(err instanceof DropboxApiError)) {
+        throw err;
+    }
+    const summary = err.errorSummary;
+    if (summary.startsWith("path/not_found") ||
+        summary.startsWith("path_lookup/not_found")) {
+        return enoent(path);
+    }
+    if (summary.startsWith("path/conflict") ||
+        summary.startsWith("to/conflict")) {
+        return eexist(path);
+    }
+    if (summary.startsWith("path/not_file")) {
+        return eisdir(path);
+    }
+    if (summary.startsWith("path/not_folder")) {
+        return enotdir(path);
+    }
+    if (summary.startsWith("path/insufficient_space") ||
+        summary.startsWith("insufficient_quota")) {
+        return enospc(path);
+    }
+    if (summary.startsWith("from_lookup/not_found")) {
+        return enoent(path);
+    }
+    // HTTP status-based mapping
+    if (err.status === 401) {
+        return new FsError("EACCES", "access token expired or invalid — refresh your token", path);
+    }
+    if (err.status === 403) {
+        return new FsError("EACCES", "access denied — check app permissions", path);
+    }
+    // For unmapped errors, wrap as-is with the path context
+    return new FsError("EIO", summary, path);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+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";

package/dist/index.js

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

package/dist/paths.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Path normalization for Dropbox API.
+ *
+ * Dropbox quirks:
+ * - Root is "" (empty string), not "/"
+ * - All other paths start with "/"
+ * - Paths are case-insensitive but case-preserving
+ */
+/**
+ * Normalize a path for Dropbox API consumption.
+ * Removes trailing slashes, collapses doubles, handles root.
+ */
+export declare function toDropboxPath(path: string, rootPath?: string): string;
+/**
+ * Resolve a relative path against a base path.
+ * Pure function — no Dropbox API calls.
+ */
+export declare function resolvePath(base: string, target: string): string;

package/dist/paths.js

@@ -0,0 +1,73 @@
+/**
+ * Path normalization for Dropbox API.
+ *
+ * Dropbox quirks:
+ * - Root is "" (empty string), not "/"
+ * - All other paths start with "/"
+ * - Paths are case-insensitive but case-preserving
+ */
+/**
+ * Normalize a path for Dropbox API consumption.
+ * Removes trailing slashes, collapses doubles, handles root.
+ */
+export function toDropboxPath(path, rootPath) {
+    // Normalize separators and collapse doubles
+    let normalized = path.replace(/\/+/g, "/");
+    // Remove trailing slash (unless root)
+    if (normalized.length > 1 && normalized.endsWith("/")) {
+        normalized = normalized.slice(0, -1);
+    }
+    // Apply rootPath prefix
+    if (rootPath) {
+        const cleanRoot = rootPath.replace(/\/+$/, "");
+        if (normalized === "/") {
+            normalized = cleanRoot;
+        }
+        else {
+            normalized = `${cleanRoot}${normalized}`;
+        }
+    }
+    // Dropbox root is "" not "/"
+    if (normalized === "/") {
+        return "";
+    }
+    // Ensure path starts with /
+    if (!normalized.startsWith("/")) {
+        normalized = `/${normalized}`;
+    }
+    return normalized;
+}
+/**
+ * Resolve a relative path against a base path.
+ * Pure function — no Dropbox API calls.
+ */
+export function resolvePath(base, target) {
+    // Absolute path — ignore base
+    if (target.startsWith("/")) {
+        return normalizePath(target);
+    }
+    // Relative path — join with base
+    const combined = base.endsWith("/")
+        ? `${base}${target}`
+        : `${base}/${target}`;
+    return normalizePath(combined);
+}
+/**
+ * Normalize a path: resolve . and .., collapse separators.
+ */
+function normalizePath(path) {
+    const parts = path.split("/");
+    const resolved = [];
+    for (const part of parts) {
+        if (part === "" || part === ".") {
+            continue;
+        }
+        if (part === "..") {
+            resolved.pop();
+        }
+        else {
+            resolved.push(part);
+        }
+    }
+    return `/${resolved.join("/")}`;
+}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Options for creating a DropboxFs instance.
+ */
+export interface DropboxFsOptions {
+    /** Static Dropbox access token. */
+    accessToken?: string;
+    /** Function that returns a fresh access token. Called before each API request. */
+    getAccessToken?: () => string | Promise<string>;
+    /** Scope all operations to this Dropbox folder (default: root). */
+    rootPath?: string;
+}
+export interface DropboxFileMetadata {
+    ".tag": "file";
+    name: string;
+    id: string;
+    path_lower: string;
+    path_display: string;
+    rev: string;
+    size: number;
+    client_modified: string;
+    server_modified: string;
+    content_hash?: string;
+    is_downloadable?: boolean;
+}
+export interface DropboxFolderMetadata {
+    ".tag": "folder";
+    name: string;
+    id: string;
+    path_lower: string;
+    path_display: string;
+}
+export interface DropboxDeletedMetadata {
+    ".tag": "deleted";
+    name: string;
+    path_lower: string;
+    path_display: string;
+}
+export type DropboxMetadata = DropboxFileMetadata | DropboxFolderMetadata | DropboxDeletedMetadata;
+export interface DropboxListFolderResult {
+    entries: DropboxMetadata[];
+    cursor: string;
+    has_more: boolean;
+}
+export interface DropboxErrorResponse {
+    error_summary: string;
+    error: {
+        ".tag": string;
+        [key: string]: unknown;
+    };
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "just-bash-dropbox",
+  "version": "0.1.0",
+  "description": "Dropbox filesystem adapter for just-bash",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manishrc/just-bash-dropbox.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "validate": "biome check . && tsc --noEmit && vitest run && rm -rf dist && tsc",
+    "prepublishOnly": "npm run validate"
+  },
+  "keywords": [
+    "dropbox",
+    "bash",
+    "filesystem",
+    "ai-agent",
+    "just-bash"
+  ],
+  "author": "",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "peerDependencies": {
+    "just-bash": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "just-bash": {
+      "optional": true
+    }
+  }
+}