agentfs-sdk 0.4.0-pre.1 → 0.4.0-pre.3

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * POSIX-style error codes for filesystem operations.
+ */
+export type FsErrorCode = 'ENOENT' | 'EEXIST' | 'EISDIR' | 'ENOTDIR' | 'ENOTEMPTY' | 'EPERM' | 'EINVAL' | 'ENOSYS';
+/**
+ * Filesystem syscall names for error reporting.
+ * rm, scandir and copyFile are not actual syscall but used for convenience
+ */
+export type FsSyscall = 'open' | 'stat' | 'mkdir' | 'rmdir' | 'rm' | 'unlink' | 'rename' | 'scandir' | 'copyfile' | 'access';
+export interface ErrnoException extends Error {
+    code?: FsErrorCode;
+    syscall?: FsSyscall;
+    path?: string;
+}
+export declare function createFsError(params: {
+    code: FsErrorCode;
+    syscall: FsSyscall;
+    path?: string;
+    message?: string;
+}): ErrnoException;

package/dist/errors.js

@@ -0,0 +1,13 @@
+export function createFsError(params) {
+    const { code, syscall, path, message } = params;
+    const base = message ?? code;
+    const suffix = path !== undefined
+        ? ` '${path}'`
+        : '';
+    const err = new Error(`${code}: ${base}, ${syscall}${suffix}`);
+    err.code = code;
+    err.syscall = syscall;
+    if (path !== undefined)
+        err.path = path;
+    return err;
+}

package/dist/filesystem.d.ts

@@ -1,4 +1,8 @@
 import type { DatabasePromise } from '@tursodatabase/database-common';
+export declare const S_IFMT = 61440;
+export declare const S_IFREG = 32768;
+export declare const S_IFDIR = 16384;
+export declare const S_IFLNK = 40960;
 export interface Stats {
     ino: number;
     mode: number;
@@ -40,6 +44,7 @@ export declare class Filesystem {
      * Split path into components
      */
     private splitPath;
+    private resolvePathOrThrow;
     /**
      * Resolve a path to an inode number
      */
@@ -64,12 +69,46 @@ export declare class Filesystem {
      * Get link count for an inode
      */
     private getLinkCount;
-    writeFile(path: string, content: string | Buffer): Promise<void>;
+    private getInodeMode;
+    writeFile(path: string, content: string | Buffer, options?: BufferEncoding | {
+        encoding?: BufferEncoding;
+    }): Promise<void>;
     private updateFileContent;
     readFile(path: string, options?: BufferEncoding | {
         encoding?: BufferEncoding;
     }): Promise<Buffer | string>;
     readdir(path: string): Promise<string[]>;
+    unlink(path: string): Promise<void>;
     deleteFile(path: string): Promise<void>;
     stat(path: string): Promise<Stats>;
+    /**
+     * Create a directory (non-recursive, no options yet)
+     */
+    mkdir(path: string): Promise<void>;
+    /**
+     * Remove a file or directory
+     */
+    rm(path: string, options?: {
+        force?: boolean;
+        recursive?: boolean;
+    }): Promise<void>;
+    private rmDirContentsRecursive;
+    private removeDentryAndMaybeInode;
+    /**
+   * Remove an empty directory
+   */
+    rmdir(path: string): Promise<void>;
+    /**
+   * Rename (move) a file or directory
+   */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /**
+    * Copy a file. Overwrites destination if it exists.
+    */
+    copyFile(src: string, dest: string): Promise<void>;
+    /**
+    * Test a user's permissions for the file or directory specified by path.
+    * Currently supports existence checks only (F_OK semantics).
+    */
+    access(path: string): Promise<void>;
 }

package/dist/filesystem.js

@@ -1,8 +1,10 @@
+import { createFsError } from './errors.js';
+import { assertInodeIsDirectory, assertNotRoot, assertNotSymlinkMode, assertReadableExistingInode, assertReaddirTargetInode, assertUnlinkTargetInode, assertWritableExistingInode, getInodeModeOrThrow, normalizeRmOptions, throwENOENTUnlessForce, } from './guards.js';
 // File types for mode field
-const S_IFMT = 0o170000; // File type mask
-const S_IFREG = 0o100000; // Regular file
-const S_IFDIR = 0o040000; // Directory
-const S_IFLNK = 0o120000; // Symbolic link
+export const S_IFMT = 0o170000; // File type mask
+export const S_IFREG = 0o100000; // Regular file
+export const S_IFDIR = 0o040000; // Directory
+export const S_IFLNK = 0o120000; // Symbolic link
 // Default permissions
 const DEFAULT_FILE_MODE = S_IFREG | 0o644; // Regular file, rw-r--r--
 const DEFAULT_DIR_MODE = S_IFDIR | 0o755; // Directory, rwxr-xr-x
@@ -43,6 +45,7 @@ export class Filesystem {
       CREATE TABLE IF NOT EXISTS fs_inode (
         ino INTEGER PRIMARY KEY AUTOINCREMENT,
         mode INTEGER NOT NULL,
+        nlink INTEGER NOT NULL DEFAULT 0,
         uid INTEGER NOT NULL DEFAULT 0,
         gid INTEGER NOT NULL DEFAULT 0,
         size INTEGER NOT NULL DEFAULT 0,
@@ -109,8 +112,8 @@ export class Filesystem {
         if (!root) {
             const now = Math.floor(Date.now() / 1000);
             const insertStmt = this.db.prepare(`
-        INSERT INTO fs_inode (ino, mode, uid, gid, size, atime, mtime, ctime)
-        VALUES (?, ?, 0, 0, 0, ?, ?, ?)
+        INSERT INTO fs_inode (ino, mode, nlink, uid, gid, size, atime, mtime, ctime)
+        VALUES (?, ?, 1, 0, 0, 0, ?, ?, ?)
       `);
             await insertStmt.run(this.rootIno, DEFAULT_DIR_MODE, now, now, now);
         }
@@ -134,6 +137,19 @@ export class Filesystem {
             return [];
         return normalized.split('/').filter(p => p);
     }
+    async resolvePathOrThrow(path, syscall) {
+        const normalizedPath = this.normalizePath(path);
+        const ino = await this.resolvePath(normalizedPath);
+        if (ino === null) {
+            throw createFsError({
+                code: 'ENOENT',
+                syscall,
+                path: normalizedPath,
+                message: 'no such file or directory',
+            });
+        }
+        return { normalizedPath, ino };
+    }
     /**
      * Resolve a path to an inode number
      */
@@ -198,6 +214,9 @@ export class Filesystem {
       VALUES (?, ?, ?)
     `);
         await stmt.run(name, parentIno, ino);
+        // Increment link count
+        const updateStmt = this.db.prepare('UPDATE fs_inode SET nlink = nlink + 1 WHERE ino = ?');
+        await updateStmt.run(ino);
     }
     /**
      * Ensure parent directories exist
@@ -207,9 +226,7 @@ export class Filesystem {
         // Remove the filename, keep only directory parts
         parts.pop();
         let currentIno = this.rootIno;
-        let currentPath = '';
         for (const name of parts) {
-            currentPath += '/' + name;
             // Check if this directory exists
             const stmt = this.db.prepare(`
         SELECT ino FROM fs_dentry
@@ -223,6 +240,8 @@ export class Filesystem {
                 currentIno = dirIno;
             }
             else {
+                // Ensure existing path component is actually a directory
+                await assertInodeIsDirectory(this.db, result.ino, 'open', this.normalizePath(path));
                 currentIno = result.ino;
             }
         }
@@ -231,35 +250,54 @@ export class Filesystem {
      * Get link count for an inode
      */
     async getLinkCount(ino) {
-        const stmt = this.db.prepare('SELECT COUNT(*) as count FROM fs_dentry WHERE ino = ?');
+        const stmt = this.db.prepare('SELECT nlink FROM fs_inode WHERE ino = ?');
         const result = await stmt.get(ino);
-        return result.count;
+        return result?.nlink ?? 0;
     }
-    async writeFile(path, content) {
+    async getInodeMode(ino) {
+        const stmt = this.db.prepare('SELECT mode FROM fs_inode WHERE ino = ?');
+        const row = await stmt.get(ino);
+        return row?.mode ?? null;
+    }
+    async writeFile(path, content, options) {
         // Ensure parent directories exist
         await this.ensureParentDirs(path);
         // Check if file already exists
         const ino = await this.resolvePath(path);
+        const encoding = typeof options === 'string'
+            ? options
+            : options?.encoding;
+        const normalizedPath = this.normalizePath(path);
         if (ino !== null) {
+            await assertWritableExistingInode(this.db, ino, 'open', normalizedPath);
             // Update existing file
-            await this.updateFileContent(ino, content);
+            await this.updateFileContent(ino, content, encoding);
         }
         else {
             // Create new file
             const parent = await this.resolveParent(path);
             if (!parent) {
-                throw new Error(`ENOENT: parent directory does not exist: ${path}`);
+                throw createFsError({
+                    code: 'ENOENT',
+                    syscall: 'open',
+                    path: normalizedPath,
+                    message: 'no such file or directory',
+                });
             }
+            // Ensure parent is a directory
+            await assertInodeIsDirectory(this.db, parent.parentIno, 'open', normalizedPath);
             // Create inode
             const fileIno = await this.createInode(DEFAULT_FILE_MODE);
             // Create directory entry
             await this.createDentry(parent.parentIno, parent.name, fileIno);
             // Write content
-            await this.updateFileContent(fileIno, content);
+            await this.updateFileContent(fileIno, content, encoding);
         }
     }
-    async updateFileContent(ino, content) {
-        const buffer = typeof content === 'string' ? this.bufferCtor.from(content, 'utf-8') : content;
+    async updateFileContent(ino, content, encoding) {
+        const buffer = typeof content === 'string'
+            ? this.bufferCtor.from(content, encoding ?? 'utf8')
+            : content;
         const now = Math.floor(Date.now() / 1000);
         // Delete existing data chunks
         const deleteStmt = this.db.prepare('DELETE FROM fs_data WHERE ino = ?');
@@ -290,10 +328,8 @@ export class Filesystem {
         const encoding = typeof options === 'string'
             ? options
             : options?.encoding;
-        const ino = await this.resolvePath(path);
-        if (ino === null) {
-            throw new Error(`ENOENT: no such file or directory, open '${path}'`);
-        }
+        const { normalizedPath, ino } = await this.resolvePathOrThrow(path, 'open');
+        await assertReadableExistingInode(this.db, ino, 'open', normalizedPath);
         // Get all data chunks
         const stmt = this.db.prepare(`
       SELECT data FROM fs_data
@@ -320,10 +356,8 @@ export class Filesystem {
         return combined;
     }
     async readdir(path) {
-        const ino = await this.resolvePath(path);
-        if (ino === null) {
-            throw new Error(`ENOENT: no such file or directory, scandir '${path}'`);
-        }
+        const { normalizedPath, ino } = await this.resolvePathOrThrow(path, 'scandir');
+        await assertReaddirTargetInode(this.db, ino, normalizedPath);
         // Get all directory entries
         const stmt = this.db.prepare(`
       SELECT name FROM fs_dentry
@@ -333,21 +367,22 @@ export class Filesystem {
         const rows = await stmt.all(ino);
         return rows.map(row => row.name);
     }
-    async deleteFile(path) {
-        const ino = await this.resolvePath(path);
-        if (ino === null) {
-            throw new Error(`ENOENT: no such file or directory, unlink '${path}'`);
-        }
-        const parent = await this.resolveParent(path);
-        if (!parent) {
-            throw new Error(`Cannot delete root directory`);
-        }
+    async unlink(path) {
+        const normalizedPath = this.normalizePath(path);
+        assertNotRoot(normalizedPath, 'unlink');
+        const { ino } = await this.resolvePathOrThrow(normalizedPath, 'unlink');
+        await assertUnlinkTargetInode(this.db, ino, normalizedPath);
+        const parent = (await this.resolveParent(normalizedPath));
+        // parent is guaranteed to exist here since normalizedPath !== '/'
         // Delete the directory entry
         const stmt = this.db.prepare(`
       DELETE FROM fs_dentry
       WHERE parent_ino = ? AND name = ?
     `);
         await stmt.run(parent.parentIno, parent.name);
+        // Decrement link count
+        const decrementStmt = this.db.prepare('UPDATE fs_inode SET nlink = nlink - 1 WHERE ino = ?');
+        await decrementStmt.run(ino);
         // Check if this was the last link to the inode
         const linkCount = await this.getLinkCount(ino);
         if (linkCount === 0) {
@@ -359,25 +394,30 @@ export class Filesystem {
             await deleteDataStmt.run(ino);
         }
     }
+    // Backwards-compatible alias
+    async deleteFile(path) {
+        return await this.unlink(path);
+    }
     async stat(path) {
-        const ino = await this.resolvePath(path);
-        if (ino === null) {
-            throw new Error(`ENOENT: no such file or directory, stat '${path}'`);
-        }
+        const { normalizedPath, ino } = await this.resolvePathOrThrow(path, 'stat');
         const stmt = this.db.prepare(`
-      SELECT ino, mode, uid, gid, size, atime, mtime, ctime
+      SELECT ino, mode, nlink, uid, gid, size, atime, mtime, ctime
       FROM fs_inode
       WHERE ino = ?
     `);
         const row = await stmt.get(ino);
         if (!row) {
-            throw new Error(`Inode not found: ${ino}`);
+            throw createFsError({
+                code: 'ENOENT',
+                syscall: 'stat',
+                path: normalizedPath,
+                message: 'no such file or directory',
+            });
         }
-        const nlink = await this.getLinkCount(ino);
         return {
             ino: row.ino,
             mode: row.mode,
-            nlink: nlink,
+            nlink: row.nlink,
             uid: row.uid,
             gid: row.gid,
             size: row.size,
@@ -389,4 +429,399 @@ export class Filesystem {
             isSymbolicLink: () => (row.mode & S_IFMT) === S_IFLNK,
         };
     }
+    /**
+     * Create a directory (non-recursive, no options yet)
+     */
+    async mkdir(path) {
+        const normalizedPath = this.normalizePath(path);
+        const existing = await this.resolvePath(normalizedPath);
+        if (existing !== null) {
+            throw createFsError({
+                code: 'EEXIST',
+                syscall: 'mkdir',
+                path: normalizedPath,
+                message: 'file already exists',
+            });
+        }
+        const parent = await this.resolveParent(normalizedPath);
+        if (!parent) {
+            throw createFsError({
+                code: 'ENOENT',
+                syscall: 'mkdir',
+                path: normalizedPath,
+                message: 'no such file or directory',
+            });
+        }
+        await assertInodeIsDirectory(this.db, parent.parentIno, 'mkdir', normalizedPath);
+        const dirIno = await this.createInode(DEFAULT_DIR_MODE);
+        try {
+            await this.createDentry(parent.parentIno, parent.name, dirIno);
+        }
+        catch {
+            throw createFsError({
+                code: 'EEXIST',
+                syscall: 'mkdir',
+                path: normalizedPath,
+                message: 'file already exists',
+            });
+        }
+    }
+    /**
+     * Remove a file or directory
+     */
+    async rm(path, options) {
+        const normalizedPath = this.normalizePath(path);
+        const { force, recursive } = normalizeRmOptions(options);
+        assertNotRoot(normalizedPath, 'rm');
+        const ino = await this.resolvePath(normalizedPath);
+        if (ino === null) {
+            throwENOENTUnlessForce(normalizedPath, 'rm', force);
+            return;
+        }
+        const mode = await getInodeModeOrThrow(this.db, ino, 'rm', normalizedPath);
+        assertNotSymlinkMode(mode, 'rm', normalizedPath);
+        const parent = await this.resolveParent(normalizedPath);
+        if (!parent) {
+            throw createFsError({
+                code: 'EPERM',
+                syscall: 'rm',
+                path: normalizedPath,
+                message: 'operation not permitted',
+            });
+        }
+        if ((mode & S_IFMT) === S_IFDIR) {
+            if (!recursive) {
+                throw createFsError({
+                    code: 'EISDIR',
+                    syscall: 'rm',
+                    path: normalizedPath,
+                    message: 'illegal operation on a directory',
+                });
+            }
+            await this.rmDirContentsRecursive(ino);
+            await this.removeDentryAndMaybeInode(parent.parentIno, parent.name, ino);
+            return;
+        }
+        // Regular file
+        await this.removeDentryAndMaybeInode(parent.parentIno, parent.name, ino);
+    }
+    async rmDirContentsRecursive(dirIno) {
+        const stmt = this.db.prepare(`
+      SELECT name, ino FROM fs_dentry
+      WHERE parent_ino = ?
+      ORDER BY name ASC
+    `);
+        const children = await stmt.all(dirIno);
+        for (const child of children) {
+            const mode = await this.getInodeMode(child.ino);
+            if (mode === null) {
+                // DB inconsistency; treat as already gone
+                continue;
+            }
+            if ((mode & S_IFMT) === S_IFDIR) {
+                await this.rmDirContentsRecursive(child.ino);
+                await this.removeDentryAndMaybeInode(dirIno, child.name, child.ino);
+            }
+            else {
+                // Not supported yet (symlinks)
+                assertNotSymlinkMode(mode, 'rm', '<symlink>');
+                await this.removeDentryAndMaybeInode(dirIno, child.name, child.ino);
+            }
+        }
+    }
+    async removeDentryAndMaybeInode(parentIno, name, ino) {
+        const stmt = this.db.prepare(`
+      DELETE FROM fs_dentry
+      WHERE parent_ino = ? AND name = ?
+    `);
+        await stmt.run(parentIno, name);
+        // Decrement link count
+        const decrementStmt = this.db.prepare('UPDATE fs_inode SET nlink = nlink - 1 WHERE ino = ?');
+        await decrementStmt.run(ino);
+        const linkCount = await this.getLinkCount(ino);
+        if (linkCount === 0) {
+            const deleteInodeStmt = this.db.prepare('DELETE FROM fs_inode WHERE ino = ?');
+            await deleteInodeStmt.run(ino);
+            const deleteDataStmt = this.db.prepare('DELETE FROM fs_data WHERE ino = ?');
+            await deleteDataStmt.run(ino);
+        }
+    }
+    /**
+   * Remove an empty directory
+   */
+    async rmdir(path) {
+        const normalizedPath = this.normalizePath(path);
+        assertNotRoot(normalizedPath, 'rmdir');
+        const { ino } = await this.resolvePathOrThrow(normalizedPath, 'rmdir');
+        const mode = await getInodeModeOrThrow(this.db, ino, 'rmdir', normalizedPath);
+        assertNotSymlinkMode(mode, 'rmdir', normalizedPath);
+        if ((mode & S_IFMT) !== S_IFDIR) {
+            throw createFsError({
+                code: 'ENOTDIR',
+                syscall: 'rmdir',
+                path: normalizedPath,
+                message: 'not a directory',
+            });
+        }
+        const stmt = this.db.prepare(`
+        SELECT 1 as one FROM fs_dentry
+        WHERE parent_ino = ?
+        LIMIT 1
+      `);
+        const child = await stmt.get(ino);
+        if (child) {
+            throw createFsError({
+                code: 'ENOTEMPTY',
+                syscall: 'rmdir',
+                path: normalizedPath,
+                message: 'directory not empty',
+            });
+        }
+        const parent = await this.resolveParent(normalizedPath);
+        if (!parent) {
+            throw createFsError({
+                code: 'EPERM',
+                syscall: 'rmdir',
+                path: normalizedPath,
+                message: 'operation not permitted',
+            });
+        }
+        await this.removeDentryAndMaybeInode(parent.parentIno, parent.name, ino);
+    }
+    /**
+   * Rename (move) a file or directory
+   */
+    async rename(oldPath, newPath) {
+        const oldNormalized = this.normalizePath(oldPath);
+        const newNormalized = this.normalizePath(newPath);
+        // No-op
+        if (oldNormalized === newNormalized)
+            return;
+        assertNotRoot(oldNormalized, 'rename');
+        assertNotRoot(newNormalized, 'rename');
+        const oldParent = await this.resolveParent(oldNormalized);
+        if (!oldParent) {
+            throw createFsError({
+                code: 'EPERM',
+                syscall: 'rename',
+                path: oldNormalized,
+                message: 'operation not permitted',
+            });
+        }
+        const newParent = await this.resolveParent(newNormalized);
+        if (!newParent) {
+            throw createFsError({
+                code: 'ENOENT',
+                syscall: 'rename',
+                path: newNormalized,
+                message: 'no such file or directory',
+            });
+        }
+        // Ensure destination parent exists and is a directory
+        await assertInodeIsDirectory(this.db, newParent.parentIno, 'rename', newNormalized);
+        await this.db.exec('BEGIN');
+        try {
+            const oldResolved = await this.resolvePathOrThrow(oldNormalized, 'rename');
+            const oldIno = oldResolved.ino;
+            const oldMode = await getInodeModeOrThrow(this.db, oldIno, 'rename', oldNormalized);
+            assertNotSymlinkMode(oldMode, 'rename', oldNormalized);
+            const oldIsDir = (oldMode & S_IFMT) === S_IFDIR;
+            // Prevent renaming a directory into its own subtree (would create cycles).
+            if (oldIsDir && newNormalized.startsWith(oldNormalized + '/')) {
+                throw createFsError({
+                    code: 'EINVAL',
+                    syscall: 'rename',
+                    path: newNormalized,
+                    message: 'invalid argument',
+                });
+            }
+            const newIno = await this.resolvePath(newNormalized);
+            if (newIno !== null) {
+                const newMode = await getInodeModeOrThrow(this.db, newIno, 'rename', newNormalized);
+                assertNotSymlinkMode(newMode, 'rename', newNormalized);
+                const newIsDir = (newMode & S_IFMT) === S_IFDIR;
+                if (newIsDir && !oldIsDir) {
+                    throw createFsError({
+                        code: 'EISDIR',
+                        syscall: 'rename',
+                        path: newNormalized,
+                        message: 'illegal operation on a directory',
+                    });
+                }
+                if (!newIsDir && oldIsDir) {
+                    throw createFsError({
+                        code: 'ENOTDIR',
+                        syscall: 'rename',
+                        path: newNormalized,
+                        message: 'not a directory',
+                    });
+                }
+                // If replacing a directory, it must be empty.
+                if (newIsDir) {
+                    const stmt = this.db.prepare(`
+              SELECT 1 as one FROM fs_dentry
+              WHERE parent_ino = ?
+              LIMIT 1
+            `);
+                    const child = await stmt.get(newIno);
+                    if (child) {
+                        throw createFsError({
+                            code: 'ENOTEMPTY',
+                            syscall: 'rename',
+                            path: newNormalized,
+                            message: 'directory not empty',
+                        });
+                    }
+                }
+                // Remove the destination entry (and inode if this was the last link)
+                await this.removeDentryAndMaybeInode(newParent.parentIno, newParent.name, newIno);
+            }
+            // Move the directory entry
+            const stmt = this.db.prepare(`
+          UPDATE fs_dentry
+          SET parent_ino = ?, name = ?
+          WHERE parent_ino = ? AND name = ?
+        `);
+            await stmt.run(newParent.parentIno, newParent.name, oldParent.parentIno, oldParent.name);
+            // Update timestamps
+            const now = Math.floor(Date.now() / 1000);
+            const updateInodeCtimeStmt = this.db.prepare(`
+          UPDATE fs_inode
+          SET ctime = ?
+          WHERE ino = ?
+        `);
+            await updateInodeCtimeStmt.run(now, oldIno);
+            const updateDirTimesStmt = this.db.prepare(`
+          UPDATE fs_inode
+          SET mtime = ?, ctime = ?
+          WHERE ino = ?
+        `);
+            await updateDirTimesStmt.run(now, now, oldParent.parentIno);
+            if (newParent.parentIno !== oldParent.parentIno) {
+                await updateDirTimesStmt.run(now, now, newParent.parentIno);
+            }
+            await this.db.exec('COMMIT');
+        }
+        catch (e) {
+            await this.db.exec('ROLLBACK');
+            throw e;
+        }
+    }
+    /**
+    * Copy a file. Overwrites destination if it exists.
+    */
+    async copyFile(src, dest) {
+        const srcNormalized = this.normalizePath(src);
+        const destNormalized = this.normalizePath(dest);
+        if (srcNormalized === destNormalized) {
+            throw createFsError({
+                code: 'EINVAL',
+                syscall: 'copyfile',
+                path: destNormalized,
+                message: 'invalid argument',
+            });
+        }
+        // Resolve and validate source
+        // node uses copyfile as syscall name even though it's not a syscall
+        const { ino: srcIno } = await this.resolvePathOrThrow(srcNormalized, 'copyfile');
+        await assertReadableExistingInode(this.db, srcIno, 'copyfile', srcNormalized);
+        const stmt = this.db.prepare(`
+      SELECT mode, uid, gid, size FROM fs_inode WHERE ino = ?
+    `);
+        const srcRow = await stmt.get(srcIno);
+        if (!srcRow) {
+            throw createFsError({
+                code: 'ENOENT',
+                syscall: 'copyfile',
+                path: srcNormalized,
+                message: 'no such file or directory',
+            });
+        }
+        // Destination parent must exist and be a directory (Node does not create parents)
+        const destParent = await this.resolveParent(destNormalized);
+        if (!destParent) {
+            throw createFsError({
+                code: 'ENOENT',
+                syscall: 'copyfile',
+                path: destNormalized,
+                message: 'no such file or directory',
+            });
+        }
+        await assertInodeIsDirectory(this.db, destParent.parentIno, 'copyfile', destNormalized);
+        await this.db.exec('BEGIN');
+        try {
+            const now = Math.floor(Date.now() / 1000);
+            // If destination exists, it must be a file (overwrite semantics).
+            const destIno = await this.resolvePath(destNormalized);
+            if (destIno !== null) {
+                const destMode = await getInodeModeOrThrow(this.db, destIno, 'copyfile', destNormalized);
+                assertNotSymlinkMode(destMode, 'copyfile', destNormalized);
+                if ((destMode & S_IFMT) === S_IFDIR) {
+                    throw createFsError({
+                        code: 'EISDIR',
+                        syscall: 'copyfile',
+                        path: destNormalized,
+                        message: 'illegal operation on a directory',
+                    });
+                }
+                // Replace destination contents
+                const deleteStmt = this.db.prepare('DELETE FROM fs_data WHERE ino = ?');
+                await deleteStmt.run(destIno);
+                const copyStmt = this.db.prepare(`
+          INSERT INTO fs_data (ino, chunk_index, data)
+          SELECT ?, chunk_index, data
+          FROM fs_data
+          WHERE ino = ?
+          ORDER BY chunk_index ASC
+        `);
+                await copyStmt.run(destIno, srcIno);
+                const updateStmt = this.db.prepare(`
+          UPDATE fs_inode
+          SET mode = ?, uid = ?, gid = ?, size = ?, mtime = ?, ctime = ?
+          WHERE ino = ?
+        `);
+                await updateStmt.run(srcRow.mode, srcRow.uid, srcRow.gid, srcRow.size, now, now, destIno);
+            }
+            else {
+                // Create new destination inode + dentry
+                const destInoCreated = await this.createInode(srcRow.mode, srcRow.uid, srcRow.gid);
+                await this.createDentry(destParent.parentIno, destParent.name, destInoCreated);
+                const copyStmt = this.db.prepare(`
+          INSERT INTO fs_data (ino, chunk_index, data)
+          SELECT ?, chunk_index, data
+          FROM fs_data
+          WHERE ino = ?
+          ORDER BY chunk_index ASC
+        `);
+                await copyStmt.run(destInoCreated, srcIno);
+                const updateStmt = this.db.prepare(`
+          UPDATE fs_inode
+          SET size = ?, mtime = ?, ctime = ?
+          WHERE ino = ?
+        `);
+                await updateStmt.run(srcRow.size, now, now, destInoCreated);
+            }
+            await this.db.exec('COMMIT');
+        }
+        catch (e) {
+            await this.db.exec('ROLLBACK');
+            throw e;
+        }
+    }
+    /**
+    * Test a user's permissions for the file or directory specified by path.
+    * Currently supports existence checks only (F_OK semantics).
+    */
+    async access(path) {
+        const normalizedPath = this.normalizePath(path);
+        const ino = await this.resolvePath(normalizedPath);
+        if (ino === null) {
+            throw createFsError({
+                code: 'ENOENT',
+                syscall: 'access',
+                path: normalizedPath,
+                message: 'no such file or directory',
+            });
+        }
+    }
 }

package/dist/guards.d.ts

@@ -0,0 +1,18 @@
+import type { DatabasePromise } from '@tursodatabase/database-common';
+import { type FsSyscall } from './errors.js';
+export declare function getInodeModeOrThrow(db: DatabasePromise, ino: number, syscall: FsSyscall, path: string): Promise<number>;
+export declare function assertNotRoot(path: string, syscall: FsSyscall): void;
+export declare function normalizeRmOptions(options?: {
+    force?: boolean;
+    recursive?: boolean;
+}): {
+    force: boolean;
+    recursive: boolean;
+};
+export declare function throwENOENTUnlessForce(path: string, syscall: FsSyscall, force: boolean): void;
+export declare function assertNotSymlinkMode(mode: number, syscall: FsSyscall, path: string): void;
+export declare function assertInodeIsDirectory(db: DatabasePromise, ino: number, syscall: FsSyscall, fullPathForError: string): Promise<void>;
+export declare function assertWritableExistingInode(db: DatabasePromise, ino: number, syscall: FsSyscall, fullPathForError: string): Promise<void>;
+export declare function assertReadableExistingInode(db: DatabasePromise, ino: number, syscall: FsSyscall, fullPathForError: string): Promise<void>;
+export declare function assertReaddirTargetInode(db: DatabasePromise, ino: number, fullPathForError: string): Promise<void>;
+export declare function assertUnlinkTargetInode(db: DatabasePromise, ino: number, fullPathForError: string): Promise<void>;

package/dist/guards.js

@@ -0,0 +1,145 @@
+import { createFsError } from './errors.js';
+import { S_IFDIR, S_IFLNK, S_IFMT } from './filesystem.js';
+async function getInodeMode(db, ino) {
+    const stmt = db.prepare('SELECT mode FROM fs_inode WHERE ino = ?');
+    const row = await stmt.get(ino);
+    return row?.mode ?? null;
+}
+function isDirMode(mode) {
+    return (mode & S_IFMT) === S_IFDIR;
+}
+export async function getInodeModeOrThrow(db, ino, syscall, path) {
+    const mode = await getInodeMode(db, ino);
+    if (mode === null) {
+        throw createFsError({
+            code: 'ENOENT',
+            syscall,
+            path,
+            message: 'no such file or directory',
+        });
+    }
+    return mode;
+}
+export function assertNotRoot(path, syscall) {
+    if (path === '/') {
+        throw createFsError({
+            code: 'EPERM',
+            syscall,
+            path,
+            message: 'operation not permitted on root directory',
+        });
+    }
+}
+export function normalizeRmOptions(options) {
+    return {
+        force: options?.force === true,
+        recursive: options?.recursive === true,
+    };
+}
+export function throwENOENTUnlessForce(path, syscall, force) {
+    if (force)
+        return;
+    throw createFsError({
+        code: 'ENOENT',
+        syscall,
+        path,
+        message: 'no such file or directory',
+    });
+}
+export function assertNotSymlinkMode(mode, syscall, path) {
+    if ((mode & S_IFMT) === S_IFLNK) {
+        throw createFsError({
+            code: 'ENOSYS',
+            syscall,
+            path,
+            message: 'symbolic links not supported yet',
+        });
+    }
+}
+async function assertExistingNonDirNonSymlinkInode(db, ino, syscall, fullPathForError) {
+    const mode = await getInodeMode(db, ino);
+    if (mode === null) {
+        throw createFsError({
+            code: 'ENOENT',
+            syscall,
+            path: fullPathForError,
+            message: 'no such file or directory',
+        });
+    }
+    if (isDirMode(mode)) {
+        throw createFsError({
+            code: 'EISDIR',
+            syscall,
+            path: fullPathForError,
+            message: 'illegal operation on a directory',
+        });
+    }
+    assertNotSymlinkMode(mode, syscall, fullPathForError);
+}
+export async function assertInodeIsDirectory(db, ino, syscall, fullPathForError) {
+    const mode = await getInodeMode(db, ino);
+    if (mode === null) {
+        throw createFsError({
+            code: 'ENOENT',
+            syscall,
+            path: fullPathForError,
+            message: 'no such file or directory',
+        });
+    }
+    if (!isDirMode(mode)) {
+        throw createFsError({
+            code: 'ENOTDIR',
+            syscall,
+            path: fullPathForError,
+            message: 'not a directory',
+        });
+    }
+}
+export async function assertWritableExistingInode(db, ino, syscall, fullPathForError) {
+    await assertExistingNonDirNonSymlinkInode(db, ino, syscall, fullPathForError);
+}
+export async function assertReadableExistingInode(db, ino, syscall, fullPathForError) {
+    await assertExistingNonDirNonSymlinkInode(db, ino, syscall, fullPathForError);
+}
+export async function assertReaddirTargetInode(db, ino, fullPathForError) {
+    const syscall = 'scandir';
+    const mode = await getInodeMode(db, ino);
+    if (mode === null) {
+        throw createFsError({
+            code: 'ENOENT',
+            syscall,
+            path: fullPathForError,
+            message: 'no such file or directory',
+        });
+    }
+    assertNotSymlinkMode(mode, syscall, fullPathForError);
+    if (!isDirMode(mode)) {
+        throw createFsError({
+            code: 'ENOTDIR',
+            syscall,
+            path: fullPathForError,
+            message: 'not a directory',
+        });
+    }
+}
+export async function assertUnlinkTargetInode(db, ino, fullPathForError) {
+    const syscall = 'unlink';
+    const mode = await getInodeMode(db, ino);
+    if (mode === null) {
+        throw createFsError({
+            code: 'ENOENT',
+            syscall,
+            path: fullPathForError,
+            message: 'no such file or directory',
+        });
+    }
+    if (isDirMode(mode)) {
+        throw createFsError({
+            code: 'EISDIR',
+            syscall,
+            path: fullPathForError,
+            message: 'illegal operation on a directory',
+        });
+    }
+    assertNotSymlinkMode(mode, syscall, fullPathForError);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfs-sdk",
-  "version": "0.4.0-pre.1",
+  "version": "0.4.0-pre.3",
   "description": "AgentFS SDK",
   "main": "dist/index_node.js",
   "types": "dist/index_node.d.ts",