just-bash-gdrive 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+## Setup
+
+```bash
+bun install
+```
+
+## Development
+
+```bash
+bun run typecheck   # TypeScript type check
+bun run test        # Run vitest suite
+bun run build       # Compile to dist/
+```
+
+## Testing
+
+Unit tests use vitest with a fetch mock — no real Drive credentials needed:
+
+```bash
+bun run test
+```
+
+For live integration testing against real Drive, set up OAuth2 credentials and run:
+
+```bash
+bun test-live.ts [optional-folder-id]
+```
+
+## Structure
+
+```
+src/
+  index.ts         — Public exports
+  gdrive-fs.ts     — IFileSystem implementation
+  gdrive-client.ts — Drive API wrapper (thin fetch layer)
+  path-cache.ts    — Bidirectional path↔ID cache
+  errors.ts        — Drive API errors → POSIX errnos
+  types.ts         — Drive API response shapes + options
+  type-check.ts    — Compile-time IFileSystem conformance check
+  gdrive-fs.test.ts — Unit tests
+```
+
+## Adding a feature
+
+1. The `IFileSystem` interface is in `node_modules/just-bash/dist/fs/interface.d.ts`
+2. All methods must match the interface exactly
+3. Run `bun run typecheck` to verify conformance
+4. Add tests for any new behavior
+
+## Publishing
+
+```bash
+bun run build
+npm publish
+```

package/README.md

@@ -0,0 +1,121 @@
+# just-bash-gdrive
+
+Google Drive filesystem adapter for [just-bash](https://github.com/vercel-labs/just-bash).
+
+Lets AI agents interact with Google Drive files using standard bash commands (`ls`, `cat`, `cp`, `grep`, etc.) without needing any Drive API knowledge.
+
+Inspired by [just-bash-dropbox](https://github.com/manishrc/just-bash-dropbox) — the same pattern, applied to Google Drive.
+
+## Install
+
+```bash
+npm install just-bash-gdrive just-bash
+```
+
+## Usage
+
+```ts
+import { Bash } from "just-bash";
+import { GDriveFs } from "just-bash-gdrive";
+
+const fs = new GDriveFs({
+  // Static token or async provider for OAuth2 refresh
+  accessToken: () => getAccessToken(),
+  // Constrain agent to a specific folder (optional)
+  rootFolderId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
+});
+
+const bash = new Bash({ fs });
+const result = await bash.exec("ls -la /");
+```
+
+### Safe mode (read-only Drive, writes go to memory)
+
+```ts
+import { Bash, MountableFs, InMemoryFs } from "just-bash";
+import { GDriveFs } from "just-bash-gdrive";
+
+const drive = new GDriveFs({ accessToken: () => getAccessToken() });
+const memory = new InMemoryFs();
+const mountable = new MountableFs(memory);
+
+// Mount Drive at /drive — writes go to memory, not Drive
+await mountable.mount("/drive", drive);
+
+const bash = new Bash({ fs: mountable });
+
+// Reads come from Drive, writes stay in memory
+await bash.exec("cat /drive/my-doc.txt");
+await bash.exec("echo 'draft' > /draft.txt"); // memory only
+```
+
+### Prefetch for glob support
+
+```ts
+const fs = new GDriveFs({ accessToken: token, rootFolderId: myFolderId });
+
+// Recursively cache all paths for glob/find support
+await fs.prefetchAllPaths();
+
+const bash = new Bash({ fs });
+await bash.exec("find / -name '*.md'"); // works after prefetch
+```
+
+### AI SDK tool
+
+```ts
+import { generateText } from "ai";
+import { bashTool } from "just-bash/ai-sdk";
+
+const { text } = await generateText({
+  model: yourModel,
+  tools: { bash: bashTool({ fs }) },
+  prompt: "List all markdown files in my Drive and summarize what they contain",
+});
+```
+
+### Getting an access token
+
+Use your preferred Google OAuth2 library. The `accessToken` option accepts either a static string or an async function — use the async form for long-running agents so the token refreshes automatically:
+
+```ts
+import { google } from "googleapis";
+
+const auth = new google.auth.OAuth2(CLIENT_ID, CLIENT_SECRET, REDIRECT_URI);
+auth.setCredentials({ refresh_token: REFRESH_TOKEN });
+
+const fs = new GDriveFs({
+  accessToken: async () => {
+    const { token } = await auth.getAccessToken();
+    return token!;
+  },
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `accessToken` | `string \| () => Promise<string>` | required | OAuth2 access token or async provider |
+| `rootFolderId` | `string` | `"root"` | Constrain agent to this Drive folder ID |
+
+## How it works
+
+Google Drive uses opaque file IDs rather than paths. `GDriveFs` maintains a bidirectional path-to-ID cache that is built lazily as you navigate the filesystem, or all at once via `prefetchAllPaths()`. Every bash command (`ls`, `cat`, `cp`, etc.) resolves paths through this cache before hitting the Drive API.
+
+Rate limit handling: automatically retries on HTTP 429 with `Retry-After` backoff (up to 3 attempts).
+
+## Limitations
+
+- `chmod`, `symlink`, `link`, `readlink`, `utimes` throw `ENOSYS` — Drive has no POSIX permission or symlink concept
+- `getAllPaths()` returns `[]` until `prefetchAllPaths()` is called — glob operations require prefetch
+- `appendFile` reads the existing file, appends, then rewrites — Drive has no atomic append
+- Google Workspace files (Docs, Sheets, Slides) cannot be read as raw content; use `gog-andy` or the Drive export API for those
+
+## Inspiration
+
+This adapter was built following the pattern established by [just-bash-dropbox](https://github.com/manishrc/just-bash-dropbox) by [@manishrc](https://github.com/manishrc). The `IFileSystem` interface, the token provider pattern, the `prefetchAllPaths` approach for glob support, and the `MountableFs` safe mode pattern are all drawn from that work. Thanks Manish.
+
+## License
+
+Apache-2.0

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+export declare class FsError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare const enoent: (path: string) => FsError;
+export declare const enotdir: (path: string) => FsError;
+export declare const eisdir: (path: string) => FsError;
+export declare const eexist: (path: string) => FsError;
+export declare const enosys: (op: string) => FsError;
+export declare const enospc: () => FsError;
+export declare class DriveApiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, body: unknown);
+}
+export declare function mapDriveError(err: DriveApiError, path: string): FsError;

package/dist/errors.js

@@ -0,0 +1,39 @@
+export class FsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "FsError";
+    }
+}
+export const enoent = (path) => new FsError("ENOENT", `no such file or directory: ${path}`);
+export const enotdir = (path) => new FsError("ENOTDIR", `not a directory: ${path}`);
+export const eisdir = (path) => new FsError("EISDIR", `illegal operation on a directory: ${path}`);
+export const eexist = (path) => new FsError("EEXIST", `file already exists: ${path}`);
+export const enosys = (op) => new FsError("ENOSYS", `${op} not supported`);
+export const enospc = () => new FsError("ENOSPC", `no space left on device`);
+export class DriveApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        const msg = typeof body === "object" && body !== null && "error" in body
+            ? body.error.message
+            : String(body);
+        super(msg);
+        this.status = status;
+        this.body = body;
+        this.name = "DriveApiError";
+    }
+}
+export function mapDriveError(err, path) {
+    switch (err.status) {
+        case 404:
+            return enoent(path);
+        case 403:
+            return new FsError("EACCES", `permission denied: ${path}`);
+        case 507:
+            return enospc();
+        default:
+            return new FsError("EIO", `drive api error ${err.status}: ${err.message}`);
+    }
+}

package/dist/gdrive-client.d.ts

@@ -0,0 +1,29 @@
+import type { DriveFileMetadata, DriveAbout } from "./types.js";
+export declare class GDriveClient {
+    private getToken;
+    constructor(accessToken: string | (() => Promise<string>));
+    private headers;
+    private request;
+    /** List files in a folder. Paginates automatically. */
+    listFolder(folderId: string): Promise<DriveFileMetadata[]>;
+    /** Get file metadata by ID */
+    getFile(fileId: string): Promise<DriveFileMetadata>;
+    /** Get file metadata by name within a parent folder */
+    findFile(name: string, parentId: string): Promise<DriveFileMetadata | null>;
+    /** Download file content */
+    downloadFile(fileId: string): Promise<Uint8Array>;
+    /** Create a new file with content */
+    createFile(name: string, parentId: string, content: Uint8Array, mimeType?: string): Promise<DriveFileMetadata>;
+    /** Update existing file content */
+    updateFile(fileId: string, content: Uint8Array): Promise<DriveFileMetadata>;
+    /** Create a folder */
+    createFolder(name: string, parentId: string): Promise<DriveFileMetadata>;
+    /** Delete a file or folder (moves to trash) */
+    delete(fileId: string): Promise<void>;
+    /** Copy a file to a new parent/name */
+    copy(fileId: string, name: string, parentId: string): Promise<DriveFileMetadata>;
+    /** Move a file by updating its parent */
+    move(fileId: string, name: string, newParentId: string, oldParentId: string): Promise<DriveFileMetadata>;
+    /** Get storage quota info */
+    getAbout(): Promise<DriveAbout>;
+}

package/dist/gdrive-client.js

@@ -0,0 +1,152 @@
+import { DriveApiError } from "./errors.js";
+import { FOLDER_MIME } from "./types.js";
+const API_BASE = "https://www.googleapis.com/drive/v3";
+const UPLOAD_BASE = "https://www.googleapis.com/upload/drive/v3";
+export class GDriveClient {
+    getToken;
+    constructor(accessToken) {
+        this.getToken =
+            typeof accessToken === "string" ? () => Promise.resolve(accessToken) : accessToken;
+    }
+    async headers() {
+        const token = await this.getToken();
+        return { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
+    }
+    async request(url, init = {}, retries = 3) {
+        const headers = await this.headers();
+        const res = await fetch(url, {
+            ...init,
+            headers: { ...headers, ...(init.headers ?? {}) },
+        });
+        if (res.status === 429 && retries > 0) {
+            const retryAfter = parseInt(res.headers.get("Retry-After") ?? "2", 10);
+            await new Promise((r) => setTimeout(r, retryAfter * 1000));
+            return this.request(url, init, retries - 1);
+        }
+        if (!res.ok) {
+            const body = await res.json().catch(() => res.statusText);
+            throw new DriveApiError(res.status, body);
+        }
+        return res.json();
+    }
+    /** List files in a folder. Paginates automatically. */
+    async listFolder(folderId) {
+        const files = [];
+        let pageToken;
+        do {
+            const params = new URLSearchParams({
+                q: `'${folderId}' in parents and trashed = false`,
+                fields: "nextPageToken,files(id,name,mimeType,size,modifiedTime,createdTime,parents)",
+                pageSize: "1000",
+                ...(pageToken ? { pageToken } : {}),
+            });
+            const res = await this.request(`${API_BASE}/files?${params}`);
+            files.push(...res.files);
+            pageToken = res.nextPageToken;
+        } while (pageToken);
+        return files;
+    }
+    /** Get file metadata by ID */
+    async getFile(fileId) {
+        const params = new URLSearchParams({
+            fields: "id,name,mimeType,size,modifiedTime,createdTime,parents",
+        });
+        return this.request(`${API_BASE}/files/${fileId}?${params}`);
+    }
+    /** Get file metadata by name within a parent folder */
+    async findFile(name, parentId) {
+        const params = new URLSearchParams({
+            q: `name = '${name.replace(/'/g, "\\'")}' and '${parentId}' in parents and trashed = false`,
+            fields: "files(id,name,mimeType,size,modifiedTime,createdTime,parents)",
+            pageSize: "1",
+        });
+        const res = await this.request(`${API_BASE}/files?${params}`);
+        return res.files[0] ?? null;
+    }
+    /** Download file content */
+    async downloadFile(fileId) {
+        const token = await this.getToken();
+        const res = await fetch(`${API_BASE}/files/${fileId}?alt=media`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => res.statusText);
+            throw new DriveApiError(res.status, body);
+        }
+        return new Uint8Array(await res.arrayBuffer());
+    }
+    /** Create a new file with content */
+    async createFile(name, parentId, content, mimeType = "application/octet-stream") {
+        const metadata = { name, parents: [parentId] };
+        const form = new FormData();
+        form.append("metadata", new Blob([JSON.stringify(metadata)], { type: "application/json" }));
+        form.append("file", new Blob([content.buffer], { type: mimeType }));
+        const token = await this.getToken();
+        const res = await fetch(`${UPLOAD_BASE}/files?uploadType=multipart&fields=id,name,mimeType,size,modifiedTime,createdTime,parents`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}` },
+            body: form,
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => res.statusText);
+            throw new DriveApiError(res.status, body);
+        }
+        return res.json();
+    }
+    /** Update existing file content */
+    async updateFile(fileId, content) {
+        const token = await this.getToken();
+        const res = await fetch(`${UPLOAD_BASE}/files/${fileId}?uploadType=media&fields=id,name,mimeType,size,modifiedTime`, {
+            method: "PATCH",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/octet-stream" },
+            body: content.buffer,
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => res.statusText);
+            throw new DriveApiError(res.status, body);
+        }
+        return res.json();
+    }
+    /** Create a folder */
+    async createFolder(name, parentId) {
+        return this.request(`${API_BASE}/files`, {
+            method: "POST",
+            body: JSON.stringify({ name, mimeType: FOLDER_MIME, parents: [parentId] }),
+        });
+    }
+    /** Delete a file or folder (moves to trash) */
+    async delete(fileId) {
+        const token = await this.getToken();
+        const res = await fetch(`${API_BASE}/files/${fileId}`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok && res.status !== 204) {
+            const body = await res.json().catch(() => res.statusText);
+            throw new DriveApiError(res.status, body);
+        }
+    }
+    /** Copy a file to a new parent/name */
+    async copy(fileId, name, parentId) {
+        return this.request(`${API_BASE}/files/${fileId}/copy`, {
+            method: "POST",
+            body: JSON.stringify({ name, parents: [parentId] }),
+        });
+    }
+    /** Move a file by updating its parent */
+    async move(fileId, name, newParentId, oldParentId) {
+        const params = new URLSearchParams({
+            addParents: newParentId,
+            removeParents: oldParentId,
+            fields: "id,name,mimeType,size,modifiedTime,parents",
+        });
+        return this.request(`${API_BASE}/files/${fileId}?${params}`, {
+            method: "PATCH",
+            body: JSON.stringify({ name }),
+        });
+    }
+    /** Get storage quota info */
+    async getAbout() {
+        return this.request(`${API_BASE}/about?fields=storageQuota`);
+    }
+}

package/dist/gdrive-fs.d.ts

@@ -0,0 +1,59 @@
+import type { IFileSystem } from "just-bash";
+import type { GDriveFsOptions } from "./types.js";
+export declare class GDriveFs implements IFileSystem {
+    private client;
+    private cache;
+    private rootFolderId;
+    private prefetched;
+    constructor(options: GDriveFsOptions);
+    resolvePath(base: string, target: string): string;
+    /** Resolve a path to a Drive file ID, fetching parent chain if needed */
+    private resolveId;
+    private metaToEntry;
+    prefetchAllPaths(folderId?: string, basePath?: string): Promise<void>;
+    getAllPaths(): string[];
+    stat(path: string): Promise<{
+        isFile: boolean;
+        isDirectory: boolean;
+        isSymbolicLink: boolean;
+        size: number;
+        mtime: Date;
+        mode: number;
+    }>;
+    lstat(path: string): Promise<{
+        isFile: boolean;
+        isDirectory: boolean;
+        isSymbolicLink: boolean;
+        size: number;
+        mtime: Date;
+        mode: number;
+    }>;
+    private entryToStat;
+    exists(path: string): Promise<boolean>;
+    realpath(path: string): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    readFile(path: string): Promise<string>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<Array<{
+        name: string;
+        isDirectory: boolean;
+        isFile: boolean;
+        isSymbolicLink: boolean;
+    }>>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    appendFile(path: string, content: string | Uint8Array): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    cp(src: string, dest: string): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    chmod(_path: string, _mode: number): Promise<void>;
+    symlink(_target: string, _path: string): Promise<void>;
+    link(_existingPath: string, _newPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    utimes(_path: string, _atime: Date, _mtime: Date): Promise<void>;
+}

package/dist/gdrive-fs.js

@@ -0,0 +1,312 @@
+import { GDriveClient } from "./gdrive-client.js";
+import { PathCache, normalizePath, dirname, basename, joinPath } from "./path-cache.js";
+import { enoent, eisdir, enotdir, eexist, enosys, mapDriveError, DriveApiError } from "./errors.js";
+import { FOLDER_MIME } from "./types.js";
+export class GDriveFs {
+    client;
+    cache;
+    rootFolderId;
+    prefetched = false;
+    constructor(options) {
+        this.client = new GDriveClient(options.accessToken);
+        this.cache = new PathCache();
+        this.rootFolderId = options.rootFolderId ?? "root";
+        // Seed root
+        this.cache.set("/", {
+            id: this.rootFolderId,
+            isFolder: true,
+            mimeType: FOLDER_MIME,
+        });
+    }
+    // ── Path resolution ──────────────────────────────────────────────────────
+    resolvePath(base, target) {
+        if (target.startsWith("/"))
+            return normalizePath(target);
+        return normalizePath(base + "/" + target);
+    }
+    /** Resolve a path to a Drive file ID, fetching parent chain if needed */
+    async resolveId(path) {
+        const normalized = normalizePath(path);
+        const cached = this.cache.get(normalized);
+        if (cached)
+            return cached.id;
+        // Walk the path components to build the cache entry
+        const parts = normalized.split("/").filter(Boolean);
+        let parentId = this.rootFolderId;
+        let currentPath = "/";
+        for (const part of parts) {
+            currentPath = joinPath(currentPath, part);
+            const existing = this.cache.get(currentPath);
+            if (existing) {
+                parentId = existing.id;
+                continue;
+            }
+            try {
+                const file = await this.client.findFile(part, parentId);
+                if (!file)
+                    throw enoent(currentPath);
+                this.cache.set(currentPath, this.metaToEntry(file));
+                parentId = file.id;
+            }
+            catch (err) {
+                if (err instanceof DriveApiError)
+                    throw mapDriveError(err, currentPath);
+                throw err;
+            }
+        }
+        return this.cache.get(normalized).id;
+    }
+    metaToEntry(file) {
+        return {
+            id: file.id,
+            isFolder: file.mimeType === FOLDER_MIME,
+            mimeType: file.mimeType,
+            size: file.size ? parseInt(file.size, 10) : undefined,
+            modifiedTime: file.modifiedTime ? new Date(file.modifiedTime) : undefined,
+            createdTime: file.createdTime ? new Date(file.createdTime) : undefined,
+            parentId: file.parents?.[0],
+        };
+    }
+    // ── Prefetch (enables glob support) ─────────────────────────────────────
+    async prefetchAllPaths(folderId, basePath = "/") {
+        const id = folderId ?? this.rootFolderId;
+        const files = await this.client.listFolder(id);
+        for (const file of files) {
+            const filePath = joinPath(basePath, file.name);
+            this.cache.set(filePath, this.metaToEntry(file));
+            if (file.mimeType === FOLDER_MIME) {
+                await this.prefetchAllPaths(file.id, filePath);
+            }
+        }
+        if (!folderId)
+            this.prefetched = true;
+    }
+    getAllPaths() {
+        return this.prefetched ? this.cache.getAllPaths() : [];
+    }
+    // ── Stat / exists ────────────────────────────────────────────────────────
+    async stat(path) {
+        const normalized = normalizePath(path);
+        const cached = this.cache.get(normalized);
+        if (cached)
+            return this.entryToStat(normalized, cached);
+        const id = await this.resolveId(normalized);
+        const entry = this.cache.get(normalized);
+        return this.entryToStat(normalized, entry);
+    }
+    async lstat(path) {
+        return this.stat(path); // Drive has no symlinks
+    }
+    entryToStat(_path, entry) {
+        return {
+            isFile: !entry.isFolder,
+            isDirectory: entry.isFolder,
+            isSymbolicLink: false,
+            size: entry.size ?? 0,
+            mtime: entry.modifiedTime ?? new Date(0),
+            mode: entry.isFolder ? 0o755 : 0o644,
+        };
+    }
+    async exists(path) {
+        try {
+            await this.resolveId(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async realpath(path) {
+        await this.resolveId(path); // throws if not found
+        return normalizePath(path);
+    }
+    // ── Read ─────────────────────────────────────────────────────────────────
+    async readFileBuffer(path) {
+        const normalized = normalizePath(path);
+        const entry = this.cache.get(normalized);
+        if (entry?.isFolder)
+            throw eisdir(normalized);
+        try {
+            const id = await this.resolveId(normalized);
+            const cached = this.cache.get(normalized);
+            if (cached.isFolder)
+                throw eisdir(normalized);
+            return await this.client.downloadFile(id);
+        }
+        catch (err) {
+            if (err instanceof DriveApiError)
+                throw mapDriveError(err, normalized);
+            throw err;
+        }
+    }
+    async readFile(path) {
+        const buf = await this.readFileBuffer(path);
+        return new TextDecoder().decode(buf);
+    }
+    async readdir(path) {
+        const entries = await this.readdirWithFileTypes(path);
+        return entries.map((e) => e.name);
+    }
+    async readdirWithFileTypes(path) {
+        const normalized = normalizePath(path);
+        const id = await this.resolveId(normalized);
+        const entry = this.cache.get(normalized);
+        if (!entry.isFolder)
+            throw enotdir(normalized);
+        try {
+            const files = await this.client.listFolder(id);
+            return files.map((file) => {
+                const filePath = joinPath(normalized, file.name);
+                this.cache.set(filePath, this.metaToEntry(file));
+                const isDir = file.mimeType === FOLDER_MIME;
+                return {
+                    name: file.name,
+                    isDirectory: isDir,
+                    isFile: !isDir,
+                    isSymbolicLink: false,
+                };
+            });
+        }
+        catch (err) {
+            if (err instanceof DriveApiError)
+                throw mapDriveError(err, normalized);
+            throw err;
+        }
+    }
+    // ── Write ────────────────────────────────────────────────────────────────
+    async writeFile(path, content) {
+        const normalized = normalizePath(path);
+        const data = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        const parentPath = dirname(normalized);
+        const name = basename(normalized);
+        try {
+            const parentId = await this.resolveId(parentPath);
+            const existing = this.cache.get(normalized);
+            if (existing) {
+                if (existing.isFolder)
+                    throw eisdir(normalized);
+                await this.client.updateFile(existing.id, data);
+                this.cache.set(normalized, { ...existing, size: data.byteLength, modifiedTime: new Date() });
+            }
+            else {
+                const file = await this.client.createFile(name, parentId, data);
+                this.cache.set(normalized, this.metaToEntry(file));
+            }
+        }
+        catch (err) {
+            if (err instanceof DriveApiError)
+                throw mapDriveError(err, normalized);
+            throw err;
+        }
+    }
+    async appendFile(path, content) {
+        const normalized = normalizePath(path);
+        let existing = new Uint8Array(0);
+        if (await this.exists(normalized)) {
+            existing = await this.readFileBuffer(normalized);
+        }
+        const append = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        const combined = new Uint8Array(existing.byteLength + append.byteLength);
+        combined.set(existing, 0);
+        combined.set(append, existing.byteLength);
+        await this.writeFile(normalized, combined);
+    }
+    async mkdir(path, options) {
+        const normalized = normalizePath(path);
+        if (await this.exists(normalized)) {
+            if (!options?.recursive)
+                throw eexist(normalized);
+            return;
+        }
+        if (options?.recursive) {
+            const parent = dirname(normalized);
+            if (parent !== normalized)
+                await this.mkdir(parent, { recursive: true });
+        }
+        const parentPath = dirname(normalized);
+        const name = basename(normalized);
+        try {
+            const parentId = await this.resolveId(parentPath);
+            const folder = await this.client.createFolder(name, parentId);
+            this.cache.set(normalized, this.metaToEntry(folder));
+        }
+        catch (err) {
+            if (err instanceof DriveApiError)
+                throw mapDriveError(err, normalized);
+            throw err;
+        }
+    }
+    // ── Delete / move / copy ─────────────────────────────────────────────────
+    async rm(path, options) {
+        const normalized = normalizePath(path);
+        try {
+            const id = await this.resolveId(normalized);
+            const entry = this.cache.get(normalized);
+            if (entry.isFolder && !options?.recursive) {
+                throw new (await import("./errors.js")).FsError("EISDIR", `is a directory: ${normalized}`);
+            }
+            await this.client.delete(id);
+            // Purge from cache (including children)
+            for (const p of this.cache.getAllPaths()) {
+                if (p === normalized || p.startsWith(normalized + "/"))
+                    this.cache.delete(p);
+            }
+        }
+        catch (err) {
+            if (options?.force)
+                return;
+            if (err instanceof DriveApiError)
+                throw mapDriveError(err, normalized);
+            throw err;
+        }
+    }
+    async cp(src, dest) {
+        const srcNorm = normalizePath(src);
+        const destNorm = normalizePath(dest);
+        try {
+            const srcId = await this.resolveId(srcNorm);
+            const destParentId = await this.resolveId(dirname(destNorm));
+            const file = await this.client.copy(srcId, basename(destNorm), destParentId);
+            this.cache.set(destNorm, this.metaToEntry(file));
+        }
+        catch (err) {
+            if (err instanceof DriveApiError)
+                throw mapDriveError(err, srcNorm);
+            throw err;
+        }
+    }
+    async mv(src, dest) {
+        const srcNorm = normalizePath(src);
+        const destNorm = normalizePath(dest);
+        try {
+            const srcId = await this.resolveId(srcNorm);
+            const srcEntry = this.cache.get(srcNorm);
+            const newParentId = await this.resolveId(dirname(destNorm));
+            const oldParentId = srcEntry.parentId ?? this.rootFolderId;
+            const file = await this.client.move(srcId, basename(destNorm), newParentId, oldParentId);
+            this.cache.delete(srcNorm);
+            this.cache.set(destNorm, this.metaToEntry(file));
+        }
+        catch (err) {
+            if (err instanceof DriveApiError)
+                throw mapDriveError(err, srcNorm);
+            throw err;
+        }
+    }
+    // ── Unsupported POSIX ops ────────────────────────────────────────────────
+    async chmod(_path, _mode) {
+        throw enosys("chmod");
+    }
+    async symlink(_target, _path) {
+        throw enosys("symlink");
+    }
+    async link(_existingPath, _newPath) {
+        throw enosys("link");
+    }
+    async readlink(path) {
+        throw enosys("readlink");
+    }
+    async utimes(_path, _atime, _mtime) {
+        throw enosys("utimes");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { GDriveFs } from "./gdrive-fs.js";
+export { FsError } from "./errors.js";
+export type { GDriveFsOptions } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { GDriveFs } from "./gdrive-fs.js";
+export { FsError } from "./errors.js";

package/dist/path-cache.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Path-to-ID cache for Google Drive.
+ *
+ * Drive uses opaque file IDs, not paths. This cache maintains a
+ * bidirectional map between POSIX paths and Drive file IDs so that
+ * all filesystem operations can resolve paths without extra API calls
+ * after an initial prefetch.
+ */
+export interface CacheEntry {
+    id: string;
+    isFolder: boolean;
+    mimeType: string;
+    size?: number;
+    modifiedTime?: Date;
+    createdTime?: Date;
+    parentId?: string;
+}
+export declare class PathCache {
+    private pathToEntry;
+    private idToPath;
+    set(path: string, entry: CacheEntry): void;
+    get(path: string): CacheEntry | undefined;
+    getById(id: string): string | undefined;
+    delete(path: string): void;
+    /** Move: update path mapping when a file is renamed/moved */
+    move(oldPath: string, newPath: string): void;
+    children(parentPath: string): Array<[string, CacheEntry]>;
+    getAllPaths(): string[];
+    has(path: string): boolean;
+    clear(): void;
+}
+export declare function normalizePath(p: string): string;
+export declare function dirname(p: string): string;
+export declare function basename(p: string): string;
+export declare function joinPath(...parts: string[]): string;

package/dist/path-cache.js

@@ -0,0 +1,89 @@
+/**
+ * Path-to-ID cache for Google Drive.
+ *
+ * Drive uses opaque file IDs, not paths. This cache maintains a
+ * bidirectional map between POSIX paths and Drive file IDs so that
+ * all filesystem operations can resolve paths without extra API calls
+ * after an initial prefetch.
+ */
+export class PathCache {
+    pathToEntry = new Map();
+    idToPath = new Map();
+    set(path, entry) {
+        const normalized = normalizePath(path);
+        this.pathToEntry.set(normalized, entry);
+        this.idToPath.set(entry.id, normalized);
+    }
+    get(path) {
+        return this.pathToEntry.get(normalizePath(path));
+    }
+    getById(id) {
+        return this.idToPath.get(id);
+    }
+    delete(path) {
+        const normalized = normalizePath(path);
+        const entry = this.pathToEntry.get(normalized);
+        if (entry) {
+            this.idToPath.delete(entry.id);
+            this.pathToEntry.delete(normalized);
+        }
+    }
+    /** Move: update path mapping when a file is renamed/moved */
+    move(oldPath, newPath) {
+        const entry = this.pathToEntry.get(normalizePath(oldPath));
+        if (entry) {
+            this.delete(oldPath);
+            this.set(newPath, entry);
+        }
+    }
+    children(parentPath) {
+        const normalized = normalizePath(parentPath);
+        const prefix = normalized === "/" ? "/" : normalized + "/";
+        const result = [];
+        for (const [path, entry] of this.pathToEntry) {
+            if (path === normalized)
+                continue;
+            if (!path.startsWith(prefix))
+                continue;
+            // Only direct children (no additional slashes after prefix)
+            const rest = path.slice(prefix.length);
+            if (!rest.includes("/"))
+                result.push([path, entry]);
+        }
+        return result;
+    }
+    getAllPaths() {
+        return Array.from(this.pathToEntry.keys());
+    }
+    has(path) {
+        return this.pathToEntry.has(normalizePath(path));
+    }
+    clear() {
+        this.pathToEntry.clear();
+        this.idToPath.clear();
+    }
+}
+export function normalizePath(p) {
+    // Collapse double slashes, ensure leading slash, strip trailing slash
+    let normalized = p.replace(/\/+/g, "/");
+    if (!normalized.startsWith("/"))
+        normalized = "/" + normalized;
+    if (normalized !== "/" && normalized.endsWith("/")) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+export function dirname(p) {
+    const normalized = normalizePath(p);
+    const idx = normalized.lastIndexOf("/");
+    if (idx <= 0)
+        return "/";
+    return normalized.slice(0, idx);
+}
+export function basename(p) {
+    const normalized = normalizePath(p);
+    return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+export function joinPath(...parts) {
+    return normalizePath(parts.join("/"));
+}

package/dist/type-check.d.ts

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

package/dist/type-check.js

@@ -0,0 +1,3 @@
+const _check = {};
+void _check;
+export {};

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export interface GDriveFsOptions {
+    /** OAuth2 access token or async provider for token refresh */
+    accessToken: string | (() => Promise<string>);
+    /** Constrain agent to a specific folder by Drive folder ID. Defaults to root ("root") */
+    rootFolderId?: string;
+}
+export interface DriveFileMetadata {
+    id: string;
+    name: string;
+    mimeType: string;
+    size?: string;
+    modifiedTime?: string;
+    createdTime?: string;
+    parents?: string[];
+    md5Checksum?: string;
+}
+export interface DriveFileList {
+    nextPageToken?: string;
+    files: DriveFileMetadata[];
+}
+export interface DriveAbout {
+    storageQuota: {
+        limit?: string;
+        usage: string;
+        usageInDrive: string;
+    };
+}
+export declare const FOLDER_MIME = "application/vnd.google-apps.folder";

package/dist/types.js

@@ -0,0 +1 @@
+export const FOLDER_MIME = "application/vnd.google-apps.folder";

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "just-bash-gdrive",
+  "version": "0.1.0",
+  "description": "Google Drive filesystem adapter for just-bash",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "just-bash": ">=2.0.0"
+  },
+  "devDependencies": {
+    "just-bash": "^2.14.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  }
+}