@boba-cli/filesystem 0.1.0-alpha.2

package/README.md

@@ -0,0 +1,299 @@
+# @boba-cli/filesystem
+
+Filesystem utility functions for Boba terminal UIs. This package provides a collection of helper functions for working with the filesystem, ported from the [teacup](https://github.com/mistakenelf/teacup) Go library.
+
+This package uses `@boba-cli/machine` abstractions to ensure browser compatibility and platform independence.
+
+## Installation
+
+```bash
+npm install @boba-cli/filesystem @boba-cli/machine
+```
+
+## Features
+
+### Directory Constants
+
+- `CurrentDirectory` - Current directory (`.`)
+- `PreviousDirectory` - Previous directory (`..`)
+- `HomeDirectory` - Home directory (`~`)
+- `RootDirectory` - Root directory (`/`)
+
+### Listing Types
+
+- `DirectoriesListingType` - Filter for directories only
+- `FilesListingType` - Filter for files only
+
+## Usage
+
+All functions require `FileSystemAdapter` and/or `PathAdapter` instances from `@boba-cli/machine`. This design allows the package to work in both Node.js and browser environments.
+
+```typescript
+import { NodeFileSystemAdapter, NodePathAdapter } from '@boba-cli/machine/node'
+import { getDirectoryListing } from '@boba-cli/filesystem'
+
+// Create adapter instances
+const fs = new NodeFileSystemAdapter()
+const path = new NodePathAdapter()
+
+// Use with functions
+const entries = await getDirectoryListing(fs, '/path/to/dir')
+```
+
+## API
+
+### Directory Listing
+
+#### `getDirectoryListing(fs: FileSystemAdapter, dir: string, showHidden?: boolean): Promise<DirectoryEntry[]>`
+
+Returns a list of files and directories within a given directory.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { getDirectoryListing } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+const entries = await getDirectoryListing(fs, '/path/to/dir')
+const allEntries = await getDirectoryListing(fs, '/path/to/dir', true) // includes hidden files
+```
+
+#### `getDirectoryListingByType(fs: FileSystemAdapter, dir: string, listingType: string, showHidden?: boolean): Promise<DirectoryEntry[]>`
+
+Returns a directory listing filtered by type (directories or files).
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import {
+  getDirectoryListingByType,
+  DirectoriesListingType,
+  FilesListingType,
+} from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+const dirs = await getDirectoryListingByType(
+  fs,
+  '/path/to/dir',
+  DirectoriesListingType,
+)
+const files = await getDirectoryListingByType(fs, '/path/to/dir', FilesListingType)
+```
+
+### Directory Navigation
+
+#### `getHomeDirectory(fs: FileSystemAdapter): string`
+
+Returns the user's home directory.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { getHomeDirectory } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+const home = getHomeDirectory(fs)
+```
+
+#### `getWorkingDirectory(fs: FileSystemAdapter): string`
+
+Returns the current working directory.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { getWorkingDirectory } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+const cwd = getWorkingDirectory(fs)
+```
+
+### File Reading
+
+#### `readFileContent(fs: FileSystemAdapter, name: string): Promise<string>`
+
+Returns the contents of a file as a string.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { readFileContent } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+const content = await readFileContent(fs, '/path/to/file.txt')
+```
+
+### Size Calculation
+
+#### `getDirectoryItemSize(fs: FileSystemAdapter, path: PathAdapter, itemPath: string): Promise<number>`
+
+Calculates the size of a directory or file in bytes.
+
+```typescript
+import { NodeFileSystemAdapter, NodePathAdapter } from '@boba-cli/machine/node'
+import { getDirectoryItemSize } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+const path = new NodePathAdapter()
+const size = await getDirectoryItemSize(fs, path, '/path/to/item')
+console.log(`Size: ${size} bytes`)
+```
+
+### File Search
+
+#### `findFilesByName(fs: FileSystemAdapter, path: PathAdapter, name: string, dir: string): Promise<{ paths: string[]; entries: DirectoryEntry[] }>`
+
+Searches for files by name (supports partial matches).
+
+```typescript
+import { NodeFileSystemAdapter, NodePathAdapter } from '@boba-cli/machine/node'
+import { findFilesByName } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+const path = new NodePathAdapter()
+const { paths, entries } = await findFilesByName(fs, path, '*.txt', '/path/to/search')
+```
+
+### File Operations
+
+#### `createFile(fs: FileSystemAdapter, name: string): Promise<void>`
+
+Creates a new file.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { createFile } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+await createFile(fs, '/path/to/newfile.txt')
+```
+
+#### `deleteFile(fs: FileSystemAdapter, name: string): Promise<void>`
+
+Deletes a file.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { deleteFile } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+await deleteFile(fs, '/path/to/file.txt')
+```
+
+#### `writeToFile(fs: FileSystemAdapter, filePath: string, content: string): Promise<void>`
+
+Writes content to a file (overwrites if exists).
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { writeToFile } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+await writeToFile(fs, '/path/to/file.txt', 'Hello, World!')
+```
+
+#### `copyFile(fs: FileSystemAdapter, path: PathAdapter, name: string): Promise<string>`
+
+Copies a file with a timestamp suffix and returns the new file path.
+
+```typescript
+import { NodeFileSystemAdapter, NodePathAdapter } from '@boba-cli/machine/node'
+import { copyFile } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+const path = new NodePathAdapter()
+const newPath = await copyFile(fs, path, '/path/to/file.txt')
+// Returns: /path/to/file_1234567890.txt
+```
+
+### Directory Operations
+
+#### `createDirectory(fs: FileSystemAdapter, name: string): Promise<void>`
+
+Creates a new directory.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { createDirectory } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+await createDirectory(fs, '/path/to/newdir')
+```
+
+#### `deleteDirectory(fs: FileSystemAdapter, name: string): Promise<void>`
+
+Deletes a directory recursively.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { deleteDirectory } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+await deleteDirectory(fs, '/path/to/dir')
+```
+
+#### `copyDirectory(fs: FileSystemAdapter, path: PathAdapter, name: string): Promise<string>`
+
+Copies a directory recursively with a timestamp suffix and returns the new directory path.
+
+```typescript
+import { NodeFileSystemAdapter, NodePathAdapter } from '@boba-cli/machine/node'
+import { copyDirectory } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+const path = new NodePathAdapter()
+const newPath = await copyDirectory(fs, path, '/path/to/dir')
+// Returns: /path/to/dir_1234567890
+```
+
+### Rename and Move Operations
+
+#### `renameDirectoryItem(fs: FileSystemAdapter, src: string, dst: string): Promise<void>`
+
+Renames a file or directory.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { renameDirectoryItem } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+await renameDirectoryItem(fs, '/path/to/old.txt', '/path/to/new.txt')
+```
+
+#### `moveDirectoryItem(fs: FileSystemAdapter, src: string, dst: string): Promise<void>`
+
+Moves a file or directory to a new location.
+
+```typescript
+import { NodeFileSystemAdapter } from '@boba-cli/machine/node'
+import { moveDirectoryItem } from '@boba-cli/filesystem'
+
+const fs = new NodeFileSystemAdapter()
+await moveDirectoryItem(fs, '/path/to/file.txt', '/new/path/file.txt')
+```
+
+## Archive Operations
+
+Archive operations (zip/unzip) have been moved to `@boba-cli/machine`. Use the `ArchiveAdapter` from that package:
+
+```typescript
+import { NodeArchiveAdapter } from '@boba-cli/machine/node'
+
+const archive = new NodeArchiveAdapter()
+await archive.zip('/path/to/source', '/path/to/output.zip')
+await archive.unzip('/path/to/archive.zip', '/path/to/extract')
+```
+
+## Types
+
+### `DirectoryEntry`
+
+Represents a directory entry with the following properties and methods:
+
+- `name: string` - The name of the entry
+- `isDirectory(): boolean` - Returns true if the entry is a directory
+- `isFile(): boolean` - Returns true if the entry is a file
+- `isSymbolicLink(): boolean` - Returns true if the entry is a symbolic link
+
+## Cross-Platform Compatibility
+
+All functions use `@boba-cli/machine` adapters to ensure compatibility across Node.js and browser environments. The adapters handle platform-specific implementation details, allowing this package to provide a consistent API regardless of the runtime environment.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,187 @@
+'use strict';
+
+// src/filesystem.ts
+var CurrentDirectory = ".";
+var PreviousDirectory = "..";
+var HomeDirectory = "~";
+var RootDirectory = "/";
+var DirectoriesListingType = "directories";
+var FilesListingType = "files";
+function generateTimestampedFilename(filePath, extension, path) {
+  const timestamp = Math.floor(Date.now() / 1e3);
+  const ext = path.extname(filePath);
+  const basename = path.basename(filePath, ext);
+  const dirname = path.dirname(filePath);
+  const filename = path.basename(filePath);
+  let output;
+  if (filename.startsWith(".") && ext === "") {
+    output = path.join(dirname, `${filename}_${timestamp}${extension}`);
+  } else if (filename.startsWith(".") && ext !== "") {
+    output = path.join(dirname, `${basename}_${timestamp}${ext}${extension}`);
+  } else if (ext !== "" && extension === "") {
+    output = path.join(dirname, `${basename}_${timestamp}${ext}`);
+  } else {
+    output = path.join(dirname, `${filename}_${timestamp}${extension}`);
+  }
+  return output;
+}
+async function getDirectoryListing(fs, dir, showHidden = false) {
+  const entries = await fs.readdir(dir, {
+    withFileTypes: true
+  });
+  if (!showHidden) {
+    return entries.filter((entry) => !entry.name.startsWith("."));
+  }
+  return entries;
+}
+async function getDirectoryListingByType(fs, dir, listingType, showHidden = false) {
+  const entries = await fs.readdir(dir, {
+    withFileTypes: true
+  });
+  return entries.filter((entry) => {
+    const isHidden = entry.name.startsWith(".");
+    if (!showHidden && isHidden) {
+      return false;
+    }
+    if (listingType === DirectoriesListingType) {
+      return entry.isDirectory();
+    } else if (listingType === FilesListingType) {
+      return entry.isFile();
+    }
+    return false;
+  });
+}
+function getHomeDirectory(fs) {
+  return fs.homedir();
+}
+function getWorkingDirectory(fs) {
+  return fs.cwd();
+}
+async function readFileContent(fs, name) {
+  const content = await fs.readFile(name, "utf-8");
+  return content;
+}
+async function getDirectoryItemSize(fs, path, itemPath) {
+  const stats = await fs.stat(itemPath);
+  if (!stats.isDirectory) {
+    return stats.size;
+  }
+  let totalSize = 0;
+  const entries = await fs.readdir(itemPath, {
+    withFileTypes: true
+  });
+  for (const entry of entries) {
+    const fullPath = path.join(itemPath, entry.name);
+    if (entry.isDirectory()) {
+      totalSize += await getDirectoryItemSize(fs, path, fullPath);
+    } else {
+      const fileStats = await fs.stat(fullPath);
+      totalSize += fileStats.size;
+    }
+  }
+  return totalSize;
+}
+async function findFilesByName(fs, path, name, dir) {
+  const paths = [];
+  const entries = [];
+  async function search(searchDir) {
+    try {
+      const items = await fs.readdir(searchDir, {
+        withFileTypes: true
+      });
+      for (const item of items) {
+        const fullPath = path.join(searchDir, item.name);
+        if (item.name.includes(name)) {
+          paths.push(fullPath);
+          entries.push(item);
+        }
+        if (item.isDirectory()) {
+          await search(fullPath);
+        }
+      }
+    } catch {
+    }
+  }
+  await search(dir);
+  return { paths, entries };
+}
+async function createFile(fs, name) {
+  await fs.writeFile(name, "");
+}
+async function createDirectory(fs, name) {
+  const exists = await fs.exists(name);
+  if (!exists) {
+    await fs.mkdir(name, { recursive: false });
+  }
+}
+async function deleteFile(fs, name) {
+  await fs.unlink(name);
+}
+async function deleteDirectory(fs, name) {
+  await fs.rmdir(name, { recursive: true, force: true });
+}
+async function renameDirectoryItem(fs, src, dst) {
+  await fs.rename(src, dst);
+}
+async function moveDirectoryItem(fs, src, dst) {
+  await fs.rename(src, dst);
+}
+async function copyFile(fs, path, name) {
+  const output = generateTimestampedFilename(name, "", path);
+  await fs.copyFile(name, output);
+  return output;
+}
+async function copyDirectory(fs, path, name) {
+  const timestamp = Math.floor(Date.now() / 1e3);
+  const output = `${name}_${timestamp}`;
+  async function copyRecursive(src, dest) {
+    const stats = await fs.stat(src);
+    if (stats.isDirectory) {
+      await fs.mkdir(dest, { recursive: true });
+      const entries = await fs.readdir(src, {
+        withFileTypes: true
+      });
+      for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+          await copyRecursive(srcPath, destPath);
+        } else {
+          await fs.copyFile(srcPath, destPath);
+        }
+      }
+    } else {
+      await fs.copyFile(src, dest);
+    }
+  }
+  await copyRecursive(name, output);
+  return output;
+}
+async function writeToFile(fs, filePath, content) {
+  await fs.writeFile(filePath, content);
+}
+
+exports.CurrentDirectory = CurrentDirectory;
+exports.DirectoriesListingType = DirectoriesListingType;
+exports.FilesListingType = FilesListingType;
+exports.HomeDirectory = HomeDirectory;
+exports.PreviousDirectory = PreviousDirectory;
+exports.RootDirectory = RootDirectory;
+exports.copyDirectory = copyDirectory;
+exports.copyFile = copyFile;
+exports.createDirectory = createDirectory;
+exports.createFile = createFile;
+exports.deleteDirectory = deleteDirectory;
+exports.deleteFile = deleteFile;
+exports.findFilesByName = findFilesByName;
+exports.getDirectoryItemSize = getDirectoryItemSize;
+exports.getDirectoryListing = getDirectoryListing;
+exports.getDirectoryListingByType = getDirectoryListingByType;
+exports.getHomeDirectory = getHomeDirectory;
+exports.getWorkingDirectory = getWorkingDirectory;
+exports.moveDirectoryItem = moveDirectoryItem;
+exports.readFileContent = readFileContent;
+exports.renameDirectoryItem = renameDirectoryItem;
+exports.writeToFile = writeToFile;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/filesystem.ts"],"names":[],"mappings":";;;AAUO,IAAM,gBAAA,GAAmB;AAMzB,IAAM,iBAAA,GAAoB;AAM1B,IAAM,aAAA,GAAgB;AAMtB,IAAM,aAAA,GAAgB;AAMtB,IAAM,sBAAA,GAAyB;AAM/B,IAAM,gBAAA,GAAmB;AAShC,SAAS,2BAAA,CACP,QAAA,EACA,SAAA,EACA,IAAA,EACQ;AACR,EAAA,MAAM,YAAY,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,GAAA,KAAQ,GAAI,CAAA;AAC9C,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,OAAA,CAAQ,QAAQ,CAAA;AACjC,EAAA,MAAM,QAAA,GAAW,IAAA,CAAK,QAAA,CAAS,QAAA,EAAU,GAAG,CAAA;AAC5C,EAAA,MAAM,OAAA,GAAU,IAAA,CAAK,OAAA,CAAQ,QAAQ,CAAA;AACrC,EAAA,MAAM,QAAA,GAAW,IAAA,CAAK,QAAA,CAAS,QAAQ,CAAA;AAEvC,EAAA,IAAI,MAAA;AAEJ,EAAA,IAAI,QAAA,CAAS,UAAA,CAAW,GAAG,CAAA,IAAK,QAAQ,EAAA,EAAI;AAE1C,IAAA,MAAA,GAAS,IAAA,CAAK,KAAK,OAAA,EAAS,CAAA,EAAG,QAAQ,CAAA,CAAA,EAAI,SAAS,CAAA,EAAG,SAAS,CAAA,CAAE,CAAA;AAAA,EACpE,WAAW,QAAA,CAAS,UAAA,CAAW,GAAG,CAAA,IAAK,QAAQ,EAAA,EAAI;AAEjD,IAAA,MAAA,GAAS,IAAA,CAAK,IAAA,CAAK,OAAA,EAAS,CAAA,EAAG,QAAQ,CAAA,CAAA,EAAI,SAAS,CAAA,EAAG,GAAG,CAAA,EAAG,SAAS,CAAA,CAAE,CAAA;AAAA,EAC1E,CAAA,MAAA,IAAW,GAAA,KAAQ,EAAA,IAAM,SAAA,KAAc,EAAA,EAAI;AAEzC,IAAA,MAAA,GAAS,IAAA,CAAK,KAAK,OAAA,EAAS,CAAA,EAAG,QAAQ,CAAA,CAAA,EAAI,SAAS,CAAA,EAAG,GAAG,CAAA,CAAE,CAAA;AAAA,EAC9D,CAAA,MAGO;AAEL,IAAA,MAAA,GAAS,IAAA,CAAK,KAAK,OAAA,EAAS,CAAA,EAAG,QAAQ,CAAA,CAAA,EAAI,SAAS,CAAA,EAAG,SAAS,CAAA,CAAE,CAAA;AAAA,EACpE;AAEA,EAAA,OAAO,MAAA;AACT;AAUA,eAAsB,mBAAA,CACpB,EAAA,EACA,GAAA,EACA,UAAA,GAAsB,KAAA,EACK;AAC3B,EAAA,MAAM,OAAA,GAAW,MAAM,EAAA,CAAG,OAAA,CAAQ,GAAA,EAAK;AAAA,IACrC,aAAA,EAAe;AAAA,GAChB,CAAA;AAED,EAAA,IAAI,CAAC,UAAA,EAAY;AACf,IAAA,OAAO,OAAA,CAAQ,OAAO,CAAC,KAAA,KAAU,CAAC,KAAA,CAAM,IAAA,CAAK,UAAA,CAAW,GAAG,CAAC,CAAA;AAAA,EAC9D;AAEA,EAAA,OAAO,OAAA;AACT;AAWA,eAAsB,yBAAA,CACpB,EAAA,EACA,GAAA,EACA,WAAA,EACA,aAAsB,KAAA,EACK;AAC3B,EAAA,MAAM,OAAA,GAAW,MAAM,EAAA,CAAG,OAAA,CAAQ,GAAA,EAAK;AAAA,IACrC,aAAA,EAAe;AAAA,GAChB,CAAA;AAED,EAAA,OAAO,OAAA,CAAQ,MAAA,CAAO,CAAC,KAAA,KAAU;AAC/B,IAAA,MAAM,QAAA,GAAW,KAAA,CAAM,IAAA,CAAK,UAAA,CAAW,GAAG,CAAA;AAE1C,IAAA,IAAI,CAAC,cAAc,QAAA,EAAU;AAC3B,MAAA,OAAO,KAAA;AAAA,IACT;AAEA,IAAA,IAAI,gBAAgB,sBAAA,EAAwB;AAC1C,MAAA,OAAO,MAAM,WAAA,EAAY;AAAA,IAC3B,CAAA,MAAA,IAAW,gBAAgB,gBAAA,EAAkB;AAC3C,MAAA,OAAO,MAAM,MAAA,EAAO;AAAA,IACtB;AAEA,IAAA,OAAO,KAAA;AAAA,EACT,CAAC,CAAA;AACH;AAQO,SAAS,iBAAiB,EAAA,EAA+B;AAC9D,EAAA,OAAO,GAAG,OAAA,EAAQ;AACpB;AAQO,SAAS,oBAAoB,EAAA,EAA+B;AACjE,EAAA,OAAO,GAAG,GAAA,EAAI;AAChB;AASA,eAAsB,eAAA,CACpB,IACA,IAAA,EACiB;AACjB,EAAA,MAAM,OAAA,GAAU,MAAM,EAAA,CAAG,QAAA,CAAS,MAAM,OAAO,CAAA;AAC/C,EAAA,OAAO,OAAA;AACT;AAUA,eAAsB,oBAAA,CACpB,EAAA,EACA,IAAA,EACA,QAAA,EACiB;AACjB,EAAA,MAAM,KAAA,GAAQ,MAAM,EAAA,CAAG,IAAA,CAAK,QAAQ,CAAA;AAEpC,EAAA,IAAI,CAAC,MAAM,WAAA,EAAa;AACtB,IAAA,OAAO,KAAA,CAAM,IAAA;AAAA,EACf;AAEA,EAAA,IAAI,SAAA,GAAY,CAAA;AAChB,EAAA,MAAM,OAAA,GAAW,MAAM,EAAA,CAAG,OAAA,CAAQ,QAAA,EAAU;AAAA,IAC1C,aAAA,EAAe;AAAA,GAChB,CAAA;AAED,EAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,IAAA,MAAM,QAAA,GAAW,IAAA,CAAK,IAAA,CAAK,QAAA,EAAU,MAAM,IAAI,CAAA;AAC/C,IAAA,IAAI,KAAA,CAAM,aAAY,EAAG;AACvB,MAAA,SAAA,IAAa,MAAM,oBAAA,CAAqB,EAAA,EAAI,IAAA,EAAM,QAAQ,CAAA;AAAA,IAC5D,CAAA,MAAO;AACL,MAAA,MAAM,SAAA,GAAY,MAAM,EAAA,CAAG,IAAA,CAAK,QAAQ,CAAA;AACxC,MAAA,SAAA,IAAa,SAAA,CAAU,IAAA;AAAA,IACzB;AAAA,EACF;AAEA,EAAA,OAAO,SAAA;AACT;AAWA,eAAsB,eAAA,CACpB,EAAA,EACA,IAAA,EACA,IAAA,EACA,GAAA,EACyD;AACzD,EAAA,MAAM,QAAkB,EAAC;AACzB,EAAA,MAAM,UAA4B,EAAC;AAEnC,EAAA,eAAe,OAAO,SAAA,EAAkC;AACtD,IAAA,IAAI;AACF,MAAA,MAAM,KAAA,GAAS,MAAM,EAAA,CAAG,OAAA,CAAQ,SAAA,EAAW;AAAA,QACzC,aAAA,EAAe;AAAA,OAChB,CAAA;AAED,MAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,QAAA,MAAM,QAAA,GAAW,IAAA,CAAK,IAAA,CAAK,SAAA,EAAW,KAAK,IAAI,CAAA;AAE/C,QAAA,IAAI,IAAA,CAAK,IAAA,CAAK,QAAA,CAAS,IAAI,CAAA,EAAG;AAC5B,UAAA,KAAA,CAAM,KAAK,QAAQ,CAAA;AACnB,UAAA,OAAA,CAAQ,KAAK,IAAI,CAAA;AAAA,QACnB;AAEA,QAAA,IAAI,IAAA,CAAK,aAAY,EAAG;AACtB,UAAA,MAAM,OAAO,QAAQ,CAAA;AAAA,QACvB;AAAA,MACF;AAAA,IACF,CAAA,CAAA,MAAQ;AAAA,IAGR;AAAA,EACF;AAEA,EAAA,MAAM,OAAO,GAAG,CAAA;AAEhB,EAAA,OAAO,EAAE,OAAO,OAAA,EAAQ;AAC1B;AAQA,eAAsB,UAAA,CACpB,IACA,IAAA,EACe;AAEf,EAAA,MAAM,EAAA,CAAG,SAAA,CAAU,IAAA,EAAM,EAAE,CAAA;AAC7B;AASA,eAAsB,eAAA,CACpB,IACA,IAAA,EACe;AACf,EAAA,MAAM,MAAA,GAAS,MAAM,EAAA,CAAG,MAAA,CAAO,IAAI,CAAA;AACnC,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,GAAG,KAAA,CAAM,IAAA,EAAM,EAAE,SAAA,EAAW,OAAO,CAAA;AAAA,EAC3C;AACF;AAQA,eAAsB,UAAA,CACpB,IACA,IAAA,EACe;AACf,EAAA,MAAM,EAAA,CAAG,OAAO,IAAI,CAAA;AACtB;AAQA,eAAsB,eAAA,CACpB,IACA,IAAA,EACe;AACf,EAAA,MAAM,EAAA,CAAG,MAAM,IAAA,EAAM,EAAE,WAAW,IAAA,EAAM,KAAA,EAAO,MAAM,CAAA;AACvD;AASA,eAAsB,mBAAA,CACpB,EAAA,EACA,GAAA,EACA,GAAA,EACe;AACf,EAAA,MAAM,EAAA,CAAG,MAAA,CAAO,GAAA,EAAK,GAAG,CAAA;AAC1B;AASA,eAAsB,iBAAA,CACpB,EAAA,EACA,GAAA,EACA,GAAA,EACe;AACf,EAAA,MAAM,EAAA,CAAG,MAAA,CAAO,GAAA,EAAK,GAAG,CAAA;AAC1B;AAUA,eAAsB,QAAA,CACpB,EAAA,EACA,IAAA,EACA,IAAA,EACiB;AACjB,EAAA,MAAM,MAAA,GAAS,2BAAA,CAA4B,IAAA,EAAM,EAAA,EAAI,IAAI,CAAA;AAEzD,EAAA,MAAM,EAAA,CAAG,QAAA,CAAS,IAAA,EAAM,MAAM,CAAA;AAC9B,EAAA,OAAO,MAAA;AACT;AAUA,eAAsB,aAAA,CACpB,EAAA,EACA,IAAA,EACA,IAAA,EACiB;AACjB,EAAA,MAAM,YAAY,IAAA,CAAK,KAAA,CAAM,IAAA,CAAK,GAAA,KAAQ,GAAI,CAAA;AAC9C,EAAA,MAAM,MAAA,GAAS,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,SAAS,CAAA,CAAA;AAEnC,EAAA,eAAe,aAAA,CAAc,KAAa,IAAA,EAA6B;AACrE,IAAA,MAAM,KAAA,GAAQ,MAAM,EAAA,CAAG,IAAA,CAAK,GAAG,CAAA;AAE/B,IAAA,IAAI,MAAM,WAAA,EAAa;AACrB,MAAA,MAAM,GAAG,KAAA,CAAM,IAAA,EAAM,EAAE,SAAA,EAAW,MAAM,CAAA;AACxC,MAAA,MAAM,OAAA,GAAW,MAAM,EAAA,CAAG,OAAA,CAAQ,GAAA,EAAK;AAAA,QACrC,aAAA,EAAe;AAAA,OAChB,CAAA;AAED,MAAA,KAAA,MAAW,SAAS,OAAA,EAAS;AAC3B,QAAA,MAAM,OAAA,GAAU,IAAA,CAAK,IAAA,CAAK,GAAA,EAAK,MAAM,IAAI,CAAA;AACzC,QAAA,MAAM,QAAA,GAAW,IAAA,CAAK,IAAA,CAAK,IAAA,EAAM,MAAM,IAAI,CAAA;AAE3C,QAAA,IAAI,KAAA,CAAM,aAAY,EAAG;AACvB,UAAA,MAAM,aAAA,CAAc,SAAS,QAAQ,CAAA;AAAA,QACvC,CAAA,MAAO;AACL,UAAA,MAAM,EAAA,CAAG,QAAA,CAAS,OAAA,EAAS,QAAQ,CAAA;AAAA,QACrC;AAAA,MACF;AAAA,IACF,CAAA,MAAO;AACL,MAAA,MAAM,EAAA,CAAG,QAAA,CAAS,GAAA,EAAK,IAAI,CAAA;AAAA,IAC7B;AAAA,EACF;AAEA,EAAA,MAAM,aAAA,CAAc,MAAM,MAAM,CAAA;AAChC,EAAA,OAAO,MAAA;AACT;AASA,eAAsB,WAAA,CACpB,EAAA,EACA,QAAA,EACA,OAAA,EACe;AACf,EAAA,MAAM,EAAA,CAAG,SAAA,CAAU,QAAA,EAAU,OAAO,CAAA;AACtC","file":"index.cjs","sourcesContent":["import type {\n  DirectoryEntry,\n  FileSystemAdapter,\n  PathAdapter,\n} from '@boba-cli/machine'\n\n/**\n * Directory shortcuts.\n * @public\n */\nexport const CurrentDirectory = '.'\n\n/**\n * Previous directory shortcut.\n * @public\n */\nexport const PreviousDirectory = '..'\n\n/**\n * Home directory shortcut.\n * @public\n */\nexport const HomeDirectory = '~'\n\n/**\n * Root directory shortcut.\n * @public\n */\nexport const RootDirectory = '/'\n\n/**\n * Listing type for directories only.\n * @public\n */\nexport const DirectoriesListingType = 'directories'\n\n/**\n * Listing type for files only.\n * @public\n */\nexport const FilesListingType = 'files'\n\n/**\n * Generates a timestamped filename for a copy operation.\n * @param filePath - The original file path\n * @param extension - The extension to use (e.g., \"\" for copy)\n * @param path - Path adapter for path operations\n * @returns The new filename with timestamp\n */\nfunction generateTimestampedFilename(\n  filePath: string,\n  extension: string,\n  path: PathAdapter,\n): string {\n  const timestamp = Math.floor(Date.now() / 1000)\n  const ext = path.extname(filePath)\n  const basename = path.basename(filePath, ext)\n  const dirname = path.dirname(filePath)\n  const filename = path.basename(filePath)\n\n  let output: string\n\n  if (filename.startsWith('.') && ext === '') {\n    // Hidden file with no extension (e.g., \".gitignore\")\n    output = path.join(dirname, `${filename}_${timestamp}${extension}`)\n  } else if (filename.startsWith('.') && ext !== '') {\n    // Hidden file with extension (e.g., \".config.json\")\n    output = path.join(dirname, `${basename}_${timestamp}${ext}${extension}`)\n  } else if (ext !== '' && extension === '') {\n    // Regular file with extension, copying (preserve original extension)\n    output = path.join(dirname, `${basename}_${timestamp}${ext}`)\n  } else if (ext !== '' && extension !== '') {\n    // Regular file with extension, with new extension (replace with new extension)\n    output = path.join(dirname, `${basename}_${timestamp}${extension}`)\n  } else {\n    // File without extension\n    output = path.join(dirname, `${filename}_${timestamp}${extension}`)\n  }\n\n  return output\n}\n\n/**\n * Returns a list of files and directories within a given directory.\n * @param fs - FileSystem adapter\n * @param dir - The directory path to list\n * @param showHidden - Whether to include hidden files (starting with .)\n * @returns Array of directory entries\n * @public\n */\nexport async function getDirectoryListing(\n  fs: FileSystemAdapter,\n  dir: string,\n  showHidden: boolean = false,\n): Promise<DirectoryEntry[]> {\n  const entries = (await fs.readdir(dir, {\n    withFileTypes: true,\n  })) as DirectoryEntry[]\n\n  if (!showHidden) {\n    return entries.filter((entry) => !entry.name.startsWith('.'))\n  }\n\n  return entries\n}\n\n/**\n * Returns a directory listing based on type (directories | files).\n * @param fs - FileSystem adapter\n * @param dir - The directory path to list\n * @param listingType - Type of listing: \"directories\" or \"files\"\n * @param showHidden - Whether to include hidden files (starting with .)\n * @returns Array of directory entries matching the type\n * @public\n */\nexport async function getDirectoryListingByType(\n  fs: FileSystemAdapter,\n  dir: string,\n  listingType: typeof DirectoriesListingType | typeof FilesListingType,\n  showHidden: boolean = false,\n): Promise<DirectoryEntry[]> {\n  const entries = (await fs.readdir(dir, {\n    withFileTypes: true,\n  })) as DirectoryEntry[]\n\n  return entries.filter((entry) => {\n    const isHidden = entry.name.startsWith('.')\n\n    if (!showHidden && isHidden) {\n      return false\n    }\n\n    if (listingType === DirectoriesListingType) {\n      return entry.isDirectory()\n    } else if (listingType === FilesListingType) {\n      return entry.isFile()\n    }\n\n    return false\n  })\n}\n\n/**\n * Returns the user's home directory.\n * @param fs - FileSystem adapter\n * @returns The home directory path\n * @public\n */\nexport function getHomeDirectory(fs: FileSystemAdapter): string {\n  return fs.homedir()\n}\n\n/**\n * Returns the current working directory.\n * @param fs - FileSystem adapter\n * @returns The current working directory path\n * @public\n */\nexport function getWorkingDirectory(fs: FileSystemAdapter): string {\n  return fs.cwd()\n}\n\n/**\n * Returns the contents of a file.\n * @param fs - FileSystem adapter\n * @param name - The file path to read\n * @returns The file contents as a string\n * @public\n */\nexport async function readFileContent(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<string> {\n  const content = await fs.readFile(name, 'utf-8')\n  return content\n}\n\n/**\n * Calculates size of a directory or file.\n * @param fs - FileSystem adapter\n * @param path - Path adapter\n * @param itemPath - The path to calculate size for\n * @returns The size in bytes\n * @public\n */\nexport async function getDirectoryItemSize(\n  fs: FileSystemAdapter,\n  path: PathAdapter,\n  itemPath: string,\n): Promise<number> {\n  const stats = await fs.stat(itemPath)\n\n  if (!stats.isDirectory) {\n    return stats.size\n  }\n\n  let totalSize = 0\n  const entries = (await fs.readdir(itemPath, {\n    withFileTypes: true,\n  })) as DirectoryEntry[]\n\n  for (const entry of entries) {\n    const fullPath = path.join(itemPath, entry.name)\n    if (entry.isDirectory()) {\n      totalSize += await getDirectoryItemSize(fs, path, fullPath)\n    } else {\n      const fileStats = await fs.stat(fullPath)\n      totalSize += fileStats.size\n    }\n  }\n\n  return totalSize\n}\n\n/**\n * Search for files by name.\n * @param fs - FileSystem adapter\n * @param path - Path adapter\n * @param name - The name or partial name to search for\n * @param dir - The directory to search in\n * @returns Object containing arrays of paths and entries\n * @public\n */\nexport async function findFilesByName(\n  fs: FileSystemAdapter,\n  path: PathAdapter,\n  name: string,\n  dir: string,\n): Promise<{ paths: string[]; entries: DirectoryEntry[] }> {\n  const paths: string[] = []\n  const entries: DirectoryEntry[] = []\n\n  async function search(searchDir: string): Promise<void> {\n    try {\n      const items = (await fs.readdir(searchDir, {\n        withFileTypes: true,\n      })) as DirectoryEntry[]\n\n      for (const item of items) {\n        const fullPath = path.join(searchDir, item.name)\n\n        if (item.name.includes(name)) {\n          paths.push(fullPath)\n          entries.push(item)\n        }\n\n        if (item.isDirectory()) {\n          await search(fullPath)\n        }\n      }\n    } catch {\n      // Skip directories we can't access (e.g., permission denied)\n      // This allows the search to continue even when some directories are inaccessible\n    }\n  }\n\n  await search(dir)\n\n  return { paths, entries }\n}\n\n/**\n * Creates a new file.\n * @param fs - FileSystem adapter\n * @param name - The file path to create\n * @public\n */\nexport async function createFile(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<void> {\n  // Create an empty file by writing an empty string\n  await fs.writeFile(name, '')\n}\n\n/**\n * Creates a new directory.\n * Note: Parent directories must exist. Use recursive operations if you need to create nested directories.\n * @param fs - FileSystem adapter\n * @param name - The directory path to create\n * @public\n */\nexport async function createDirectory(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<void> {\n  const exists = await fs.exists(name)\n  if (!exists) {\n    await fs.mkdir(name, { recursive: false })\n  }\n}\n\n/**\n * Deletes a file.\n * @param fs - FileSystem adapter\n * @param name - The file path to delete\n * @public\n */\nexport async function deleteFile(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<void> {\n  await fs.unlink(name)\n}\n\n/**\n * Deletes a directory recursively.\n * @param fs - FileSystem adapter\n * @param name - The directory path to delete\n * @public\n */\nexport async function deleteDirectory(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<void> {\n  await fs.rmdir(name, { recursive: true, force: true })\n}\n\n/**\n * Renames a file or directory.\n * @param fs - FileSystem adapter\n * @param src - The source path\n * @param dst - The destination path\n * @public\n */\nexport async function renameDirectoryItem(\n  fs: FileSystemAdapter,\n  src: string,\n  dst: string,\n): Promise<void> {\n  await fs.rename(src, dst)\n}\n\n/**\n * Moves a file or directory.\n * @param fs - FileSystem adapter\n * @param src - The source path\n * @param dst - The destination path\n * @public\n */\nexport async function moveDirectoryItem(\n  fs: FileSystemAdapter,\n  src: string,\n  dst: string,\n): Promise<void> {\n  await fs.rename(src, dst)\n}\n\n/**\n * Copies a file with timestamp suffix.\n * @param fs - FileSystem adapter\n * @param path - Path adapter\n * @param name - The file path to copy\n * @returns The new file path\n * @public\n */\nexport async function copyFile(\n  fs: FileSystemAdapter,\n  path: PathAdapter,\n  name: string,\n): Promise<string> {\n  const output = generateTimestampedFilename(name, '', path)\n\n  await fs.copyFile(name, output)\n  return output\n}\n\n/**\n * Copies a directory recursively with timestamp suffix.\n * @param fs - FileSystem adapter\n * @param path - Path adapter\n * @param name - The directory path to copy\n * @returns The new directory path\n * @public\n */\nexport async function copyDirectory(\n  fs: FileSystemAdapter,\n  path: PathAdapter,\n  name: string,\n): Promise<string> {\n  const timestamp = Math.floor(Date.now() / 1000)\n  const output = `${name}_${timestamp}`\n\n  async function copyRecursive(src: string, dest: string): Promise<void> {\n    const stats = await fs.stat(src)\n\n    if (stats.isDirectory) {\n      await fs.mkdir(dest, { recursive: true })\n      const entries = (await fs.readdir(src, {\n        withFileTypes: true,\n      })) as DirectoryEntry[]\n\n      for (const entry of entries) {\n        const srcPath = path.join(src, entry.name)\n        const destPath = path.join(dest, entry.name)\n\n        if (entry.isDirectory()) {\n          await copyRecursive(srcPath, destPath)\n        } else {\n          await fs.copyFile(srcPath, destPath)\n        }\n      }\n    } else {\n      await fs.copyFile(src, dest)\n    }\n  }\n\n  await copyRecursive(name, output)\n  return output\n}\n\n/**\n * Writes content to a file.\n * @param fs - FileSystem adapter\n * @param filePath - The file path to write to\n * @param content - The content to write\n * @public\n */\nexport async function writeToFile(\n  fs: FileSystemAdapter,\n  filePath: string,\n  content: string,\n): Promise<void> {\n  await fs.writeFile(filePath, content)\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,169 @@
+import { FileSystemAdapter, DirectoryEntry, PathAdapter } from '@boba-cli/machine';
+export { DirectoryEntry } from '@boba-cli/machine';
+
+/**
+ * Directory shortcuts.
+ * @public
+ */
+declare const CurrentDirectory = ".";
+/**
+ * Previous directory shortcut.
+ * @public
+ */
+declare const PreviousDirectory = "..";
+/**
+ * Home directory shortcut.
+ * @public
+ */
+declare const HomeDirectory = "~";
+/**
+ * Root directory shortcut.
+ * @public
+ */
+declare const RootDirectory = "/";
+/**
+ * Listing type for directories only.
+ * @public
+ */
+declare const DirectoriesListingType = "directories";
+/**
+ * Listing type for files only.
+ * @public
+ */
+declare const FilesListingType = "files";
+/**
+ * Returns a list of files and directories within a given directory.
+ * @param fs - FileSystem adapter
+ * @param dir - The directory path to list
+ * @param showHidden - Whether to include hidden files (starting with .)
+ * @returns Array of directory entries
+ * @public
+ */
+declare function getDirectoryListing(fs: FileSystemAdapter, dir: string, showHidden?: boolean): Promise<DirectoryEntry[]>;
+/**
+ * Returns a directory listing based on type (directories | files).
+ * @param fs - FileSystem adapter
+ * @param dir - The directory path to list
+ * @param listingType - Type of listing: "directories" or "files"
+ * @param showHidden - Whether to include hidden files (starting with .)
+ * @returns Array of directory entries matching the type
+ * @public
+ */
+declare function getDirectoryListingByType(fs: FileSystemAdapter, dir: string, listingType: typeof DirectoriesListingType | typeof FilesListingType, showHidden?: boolean): Promise<DirectoryEntry[]>;
+/**
+ * Returns the user's home directory.
+ * @param fs - FileSystem adapter
+ * @returns The home directory path
+ * @public
+ */
+declare function getHomeDirectory(fs: FileSystemAdapter): string;
+/**
+ * Returns the current working directory.
+ * @param fs - FileSystem adapter
+ * @returns The current working directory path
+ * @public
+ */
+declare function getWorkingDirectory(fs: FileSystemAdapter): string;
+/**
+ * Returns the contents of a file.
+ * @param fs - FileSystem adapter
+ * @param name - The file path to read
+ * @returns The file contents as a string
+ * @public
+ */
+declare function readFileContent(fs: FileSystemAdapter, name: string): Promise<string>;
+/**
+ * Calculates size of a directory or file.
+ * @param fs - FileSystem adapter
+ * @param path - Path adapter
+ * @param itemPath - The path to calculate size for
+ * @returns The size in bytes
+ * @public
+ */
+declare function getDirectoryItemSize(fs: FileSystemAdapter, path: PathAdapter, itemPath: string): Promise<number>;
+/**
+ * Search for files by name.
+ * @param fs - FileSystem adapter
+ * @param path - Path adapter
+ * @param name - The name or partial name to search for
+ * @param dir - The directory to search in
+ * @returns Object containing arrays of paths and entries
+ * @public
+ */
+declare function findFilesByName(fs: FileSystemAdapter, path: PathAdapter, name: string, dir: string): Promise<{
+    paths: string[];
+    entries: DirectoryEntry[];
+}>;
+/**
+ * Creates a new file.
+ * @param fs - FileSystem adapter
+ * @param name - The file path to create
+ * @public
+ */
+declare function createFile(fs: FileSystemAdapter, name: string): Promise<void>;
+/**
+ * Creates a new directory.
+ * Note: Parent directories must exist. Use recursive operations if you need to create nested directories.
+ * @param fs - FileSystem adapter
+ * @param name - The directory path to create
+ * @public
+ */
+declare function createDirectory(fs: FileSystemAdapter, name: string): Promise<void>;
+/**
+ * Deletes a file.
+ * @param fs - FileSystem adapter
+ * @param name - The file path to delete
+ * @public
+ */
+declare function deleteFile(fs: FileSystemAdapter, name: string): Promise<void>;
+/**
+ * Deletes a directory recursively.
+ * @param fs - FileSystem adapter
+ * @param name - The directory path to delete
+ * @public
+ */
+declare function deleteDirectory(fs: FileSystemAdapter, name: string): Promise<void>;
+/**
+ * Renames a file or directory.
+ * @param fs - FileSystem adapter
+ * @param src - The source path
+ * @param dst - The destination path
+ * @public
+ */
+declare function renameDirectoryItem(fs: FileSystemAdapter, src: string, dst: string): Promise<void>;
+/**
+ * Moves a file or directory.
+ * @param fs - FileSystem adapter
+ * @param src - The source path
+ * @param dst - The destination path
+ * @public
+ */
+declare function moveDirectoryItem(fs: FileSystemAdapter, src: string, dst: string): Promise<void>;
+/**
+ * Copies a file with timestamp suffix.
+ * @param fs - FileSystem adapter
+ * @param path - Path adapter
+ * @param name - The file path to copy
+ * @returns The new file path
+ * @public
+ */
+declare function copyFile(fs: FileSystemAdapter, path: PathAdapter, name: string): Promise<string>;
+/**
+ * Copies a directory recursively with timestamp suffix.
+ * @param fs - FileSystem adapter
+ * @param path - Path adapter
+ * @param name - The directory path to copy
+ * @returns The new directory path
+ * @public
+ */
+declare function copyDirectory(fs: FileSystemAdapter, path: PathAdapter, name: string): Promise<string>;
+/**
+ * Writes content to a file.
+ * @param fs - FileSystem adapter
+ * @param filePath - The file path to write to
+ * @param content - The content to write
+ * @public
+ */
+declare function writeToFile(fs: FileSystemAdapter, filePath: string, content: string): Promise<void>;
+
+export { CurrentDirectory, DirectoriesListingType, FilesListingType, HomeDirectory, PreviousDirectory, RootDirectory, copyDirectory, copyFile, createDirectory, createFile, deleteDirectory, deleteFile, findFilesByName, getDirectoryItemSize, getDirectoryListing, getDirectoryListingByType, getHomeDirectory, getWorkingDirectory, moveDirectoryItem, readFileContent, renameDirectoryItem, writeToFile };

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+import { FileSystemAdapter, DirectoryEntry, PathAdapter } from '@boba-cli/machine';
+export { DirectoryEntry } from '@boba-cli/machine';
+
+/**
+ * Directory shortcuts.
+ * @public
+ */
+declare const CurrentDirectory = ".";
+/**
+ * Previous directory shortcut.
+ * @public
+ */
+declare const PreviousDirectory = "..";
+/**
+ * Home directory shortcut.
+ * @public
+ */
+declare const HomeDirectory = "~";
+/**
+ * Root directory shortcut.
+ * @public
+ */
+declare const RootDirectory = "/";
+/**
+ * Listing type for directories only.
+ * @public
+ */
+declare const DirectoriesListingType = "directories";
+/**
+ * Listing type for files only.
+ * @public
+ */
+declare const FilesListingType = "files";
+/**
+ * Returns a list of files and directories within a given directory.
+ * @param fs - FileSystem adapter
+ * @param dir - The directory path to list
+ * @param showHidden - Whether to include hidden files (starting with .)
+ * @returns Array of directory entries
+ * @public
+ */
+declare function getDirectoryListing(fs: FileSystemAdapter, dir: string, showHidden?: boolean): Promise<DirectoryEntry[]>;
+/**
+ * Returns a directory listing based on type (directories | files).
+ * @param fs - FileSystem adapter
+ * @param dir - The directory path to list
+ * @param listingType - Type of listing: "directories" or "files"
+ * @param showHidden - Whether to include hidden files (starting with .)
+ * @returns Array of directory entries matching the type
+ * @public
+ */
+declare function getDirectoryListingByType(fs: FileSystemAdapter, dir: string, listingType: typeof DirectoriesListingType | typeof FilesListingType, showHidden?: boolean): Promise<DirectoryEntry[]>;
+/**
+ * Returns the user's home directory.
+ * @param fs - FileSystem adapter
+ * @returns The home directory path
+ * @public
+ */
+declare function getHomeDirectory(fs: FileSystemAdapter): string;
+/**
+ * Returns the current working directory.
+ * @param fs - FileSystem adapter
+ * @returns The current working directory path
+ * @public
+ */
+declare function getWorkingDirectory(fs: FileSystemAdapter): string;
+/**
+ * Returns the contents of a file.
+ * @param fs - FileSystem adapter
+ * @param name - The file path to read
+ * @returns The file contents as a string
+ * @public
+ */
+declare function readFileContent(fs: FileSystemAdapter, name: string): Promise<string>;
+/**
+ * Calculates size of a directory or file.
+ * @param fs - FileSystem adapter
+ * @param path - Path adapter
+ * @param itemPath - The path to calculate size for
+ * @returns The size in bytes
+ * @public
+ */
+declare function getDirectoryItemSize(fs: FileSystemAdapter, path: PathAdapter, itemPath: string): Promise<number>;
+/**
+ * Search for files by name.
+ * @param fs - FileSystem adapter
+ * @param path - Path adapter
+ * @param name - The name or partial name to search for
+ * @param dir - The directory to search in
+ * @returns Object containing arrays of paths and entries
+ * @public
+ */
+declare function findFilesByName(fs: FileSystemAdapter, path: PathAdapter, name: string, dir: string): Promise<{
+    paths: string[];
+    entries: DirectoryEntry[];
+}>;
+/**
+ * Creates a new file.
+ * @param fs - FileSystem adapter
+ * @param name - The file path to create
+ * @public
+ */
+declare function createFile(fs: FileSystemAdapter, name: string): Promise<void>;
+/**
+ * Creates a new directory.
+ * Note: Parent directories must exist. Use recursive operations if you need to create nested directories.
+ * @param fs - FileSystem adapter
+ * @param name - The directory path to create
+ * @public
+ */
+declare function createDirectory(fs: FileSystemAdapter, name: string): Promise<void>;
+/**
+ * Deletes a file.
+ * @param fs - FileSystem adapter
+ * @param name - The file path to delete
+ * @public
+ */
+declare function deleteFile(fs: FileSystemAdapter, name: string): Promise<void>;
+/**
+ * Deletes a directory recursively.
+ * @param fs - FileSystem adapter
+ * @param name - The directory path to delete
+ * @public
+ */
+declare function deleteDirectory(fs: FileSystemAdapter, name: string): Promise<void>;
+/**
+ * Renames a file or directory.
+ * @param fs - FileSystem adapter
+ * @param src - The source path
+ * @param dst - The destination path
+ * @public
+ */
+declare function renameDirectoryItem(fs: FileSystemAdapter, src: string, dst: string): Promise<void>;
+/**
+ * Moves a file or directory.
+ * @param fs - FileSystem adapter
+ * @param src - The source path
+ * @param dst - The destination path
+ * @public
+ */
+declare function moveDirectoryItem(fs: FileSystemAdapter, src: string, dst: string): Promise<void>;
+/**
+ * Copies a file with timestamp suffix.
+ * @param fs - FileSystem adapter
+ * @param path - Path adapter
+ * @param name - The file path to copy
+ * @returns The new file path
+ * @public
+ */
+declare function copyFile(fs: FileSystemAdapter, path: PathAdapter, name: string): Promise<string>;
+/**
+ * Copies a directory recursively with timestamp suffix.
+ * @param fs - FileSystem adapter
+ * @param path - Path adapter
+ * @param name - The directory path to copy
+ * @returns The new directory path
+ * @public
+ */
+declare function copyDirectory(fs: FileSystemAdapter, path: PathAdapter, name: string): Promise<string>;
+/**
+ * Writes content to a file.
+ * @param fs - FileSystem adapter
+ * @param filePath - The file path to write to
+ * @param content - The content to write
+ * @public
+ */
+declare function writeToFile(fs: FileSystemAdapter, filePath: string, content: string): Promise<void>;
+
+export { CurrentDirectory, DirectoriesListingType, FilesListingType, HomeDirectory, PreviousDirectory, RootDirectory, copyDirectory, copyFile, createDirectory, createFile, deleteDirectory, deleteFile, findFilesByName, getDirectoryItemSize, getDirectoryListing, getDirectoryListingByType, getHomeDirectory, getWorkingDirectory, moveDirectoryItem, readFileContent, renameDirectoryItem, writeToFile };

package/dist/index.js

@@ -0,0 +1,164 @@
+// src/filesystem.ts
+var CurrentDirectory = ".";
+var PreviousDirectory = "..";
+var HomeDirectory = "~";
+var RootDirectory = "/";
+var DirectoriesListingType = "directories";
+var FilesListingType = "files";
+function generateTimestampedFilename(filePath, extension, path) {
+  const timestamp = Math.floor(Date.now() / 1e3);
+  const ext = path.extname(filePath);
+  const basename = path.basename(filePath, ext);
+  const dirname = path.dirname(filePath);
+  const filename = path.basename(filePath);
+  let output;
+  if (filename.startsWith(".") && ext === "") {
+    output = path.join(dirname, `${filename}_${timestamp}${extension}`);
+  } else if (filename.startsWith(".") && ext !== "") {
+    output = path.join(dirname, `${basename}_${timestamp}${ext}${extension}`);
+  } else if (ext !== "" && extension === "") {
+    output = path.join(dirname, `${basename}_${timestamp}${ext}`);
+  } else {
+    output = path.join(dirname, `${filename}_${timestamp}${extension}`);
+  }
+  return output;
+}
+async function getDirectoryListing(fs, dir, showHidden = false) {
+  const entries = await fs.readdir(dir, {
+    withFileTypes: true
+  });
+  if (!showHidden) {
+    return entries.filter((entry) => !entry.name.startsWith("."));
+  }
+  return entries;
+}
+async function getDirectoryListingByType(fs, dir, listingType, showHidden = false) {
+  const entries = await fs.readdir(dir, {
+    withFileTypes: true
+  });
+  return entries.filter((entry) => {
+    const isHidden = entry.name.startsWith(".");
+    if (!showHidden && isHidden) {
+      return false;
+    }
+    if (listingType === DirectoriesListingType) {
+      return entry.isDirectory();
+    } else if (listingType === FilesListingType) {
+      return entry.isFile();
+    }
+    return false;
+  });
+}
+function getHomeDirectory(fs) {
+  return fs.homedir();
+}
+function getWorkingDirectory(fs) {
+  return fs.cwd();
+}
+async function readFileContent(fs, name) {
+  const content = await fs.readFile(name, "utf-8");
+  return content;
+}
+async function getDirectoryItemSize(fs, path, itemPath) {
+  const stats = await fs.stat(itemPath);
+  if (!stats.isDirectory) {
+    return stats.size;
+  }
+  let totalSize = 0;
+  const entries = await fs.readdir(itemPath, {
+    withFileTypes: true
+  });
+  for (const entry of entries) {
+    const fullPath = path.join(itemPath, entry.name);
+    if (entry.isDirectory()) {
+      totalSize += await getDirectoryItemSize(fs, path, fullPath);
+    } else {
+      const fileStats = await fs.stat(fullPath);
+      totalSize += fileStats.size;
+    }
+  }
+  return totalSize;
+}
+async function findFilesByName(fs, path, name, dir) {
+  const paths = [];
+  const entries = [];
+  async function search(searchDir) {
+    try {
+      const items = await fs.readdir(searchDir, {
+        withFileTypes: true
+      });
+      for (const item of items) {
+        const fullPath = path.join(searchDir, item.name);
+        if (item.name.includes(name)) {
+          paths.push(fullPath);
+          entries.push(item);
+        }
+        if (item.isDirectory()) {
+          await search(fullPath);
+        }
+      }
+    } catch {
+    }
+  }
+  await search(dir);
+  return { paths, entries };
+}
+async function createFile(fs, name) {
+  await fs.writeFile(name, "");
+}
+async function createDirectory(fs, name) {
+  const exists = await fs.exists(name);
+  if (!exists) {
+    await fs.mkdir(name, { recursive: false });
+  }
+}
+async function deleteFile(fs, name) {
+  await fs.unlink(name);
+}
+async function deleteDirectory(fs, name) {
+  await fs.rmdir(name, { recursive: true, force: true });
+}
+async function renameDirectoryItem(fs, src, dst) {
+  await fs.rename(src, dst);
+}
+async function moveDirectoryItem(fs, src, dst) {
+  await fs.rename(src, dst);
+}
+async function copyFile(fs, path, name) {
+  const output = generateTimestampedFilename(name, "", path);
+  await fs.copyFile(name, output);
+  return output;
+}
+async function copyDirectory(fs, path, name) {
+  const timestamp = Math.floor(Date.now() / 1e3);
+  const output = `${name}_${timestamp}`;
+  async function copyRecursive(src, dest) {
+    const stats = await fs.stat(src);
+    if (stats.isDirectory) {
+      await fs.mkdir(dest, { recursive: true });
+      const entries = await fs.readdir(src, {
+        withFileTypes: true
+      });
+      for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+          await copyRecursive(srcPath, destPath);
+        } else {
+          await fs.copyFile(srcPath, destPath);
+        }
+      }
+    } else {
+      await fs.copyFile(src, dest);
+    }
+  }
+  await copyRecursive(name, output);
+  return output;
+}
+async function writeToFile(fs, filePath, content) {
+  await fs.writeFile(filePath, content);
+}
+
+export { CurrentDirectory, DirectoriesListingType, FilesListingType, HomeDirectory, PreviousDirectory, RootDirectory, copyDirectory, copyFile, createDirectory, createFile, deleteDirectory, deleteFile, findFilesByName, getDirectoryItemSize, getDirectoryListing, getDirectoryListingByType, getHomeDirectory, getWorkingDirectory, moveDirectoryItem, readFileContent, renameDirectoryItem, writeToFile };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/filesystem.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type {\n  DirectoryEntry,\n  FileSystemAdapter,\n  PathAdapter,\n} from '@boba-cli/machine'\n\n/**\n * Directory shortcuts.\n * @public\n */\nexport const CurrentDirectory = '.'\n\n/**\n * Previous directory shortcut.\n * @public\n */\nexport const PreviousDirectory = '..'\n\n/**\n * Home directory shortcut.\n * @public\n */\nexport const HomeDirectory = '~'\n\n/**\n * Root directory shortcut.\n * @public\n */\nexport const RootDirectory = '/'\n\n/**\n * Listing type for directories only.\n * @public\n */\nexport const DirectoriesListingType = 'directories'\n\n/**\n * Listing type for files only.\n * @public\n */\nexport const FilesListingType = 'files'\n\n/**\n * Generates a timestamped filename for a copy operation.\n * @param filePath - The original file path\n * @param extension - The extension to use (e.g., \"\" for copy)\n * @param path - Path adapter for path operations\n * @returns The new filename with timestamp\n */\nfunction generateTimestampedFilename(\n  filePath: string,\n  extension: string,\n  path: PathAdapter,\n): string {\n  const timestamp = Math.floor(Date.now() / 1000)\n  const ext = path.extname(filePath)\n  const basename = path.basename(filePath, ext)\n  const dirname = path.dirname(filePath)\n  const filename = path.basename(filePath)\n\n  let output: string\n\n  if (filename.startsWith('.') && ext === '') {\n    // Hidden file with no extension (e.g., \".gitignore\")\n    output = path.join(dirname, `${filename}_${timestamp}${extension}`)\n  } else if (filename.startsWith('.') && ext !== '') {\n    // Hidden file with extension (e.g., \".config.json\")\n    output = path.join(dirname, `${basename}_${timestamp}${ext}${extension}`)\n  } else if (ext !== '' && extension === '') {\n    // Regular file with extension, copying (preserve original extension)\n    output = path.join(dirname, `${basename}_${timestamp}${ext}`)\n  } else if (ext !== '' && extension !== '') {\n    // Regular file with extension, with new extension (replace with new extension)\n    output = path.join(dirname, `${basename}_${timestamp}${extension}`)\n  } else {\n    // File without extension\n    output = path.join(dirname, `${filename}_${timestamp}${extension}`)\n  }\n\n  return output\n}\n\n/**\n * Returns a list of files and directories within a given directory.\n * @param fs - FileSystem adapter\n * @param dir - The directory path to list\n * @param showHidden - Whether to include hidden files (starting with .)\n * @returns Array of directory entries\n * @public\n */\nexport async function getDirectoryListing(\n  fs: FileSystemAdapter,\n  dir: string,\n  showHidden: boolean = false,\n): Promise<DirectoryEntry[]> {\n  const entries = (await fs.readdir(dir, {\n    withFileTypes: true,\n  })) as DirectoryEntry[]\n\n  if (!showHidden) {\n    return entries.filter((entry) => !entry.name.startsWith('.'))\n  }\n\n  return entries\n}\n\n/**\n * Returns a directory listing based on type (directories | files).\n * @param fs - FileSystem adapter\n * @param dir - The directory path to list\n * @param listingType - Type of listing: \"directories\" or \"files\"\n * @param showHidden - Whether to include hidden files (starting with .)\n * @returns Array of directory entries matching the type\n * @public\n */\nexport async function getDirectoryListingByType(\n  fs: FileSystemAdapter,\n  dir: string,\n  listingType: typeof DirectoriesListingType | typeof FilesListingType,\n  showHidden: boolean = false,\n): Promise<DirectoryEntry[]> {\n  const entries = (await fs.readdir(dir, {\n    withFileTypes: true,\n  })) as DirectoryEntry[]\n\n  return entries.filter((entry) => {\n    const isHidden = entry.name.startsWith('.')\n\n    if (!showHidden && isHidden) {\n      return false\n    }\n\n    if (listingType === DirectoriesListingType) {\n      return entry.isDirectory()\n    } else if (listingType === FilesListingType) {\n      return entry.isFile()\n    }\n\n    return false\n  })\n}\n\n/**\n * Returns the user's home directory.\n * @param fs - FileSystem adapter\n * @returns The home directory path\n * @public\n */\nexport function getHomeDirectory(fs: FileSystemAdapter): string {\n  return fs.homedir()\n}\n\n/**\n * Returns the current working directory.\n * @param fs - FileSystem adapter\n * @returns The current working directory path\n * @public\n */\nexport function getWorkingDirectory(fs: FileSystemAdapter): string {\n  return fs.cwd()\n}\n\n/**\n * Returns the contents of a file.\n * @param fs - FileSystem adapter\n * @param name - The file path to read\n * @returns The file contents as a string\n * @public\n */\nexport async function readFileContent(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<string> {\n  const content = await fs.readFile(name, 'utf-8')\n  return content\n}\n\n/**\n * Calculates size of a directory or file.\n * @param fs - FileSystem adapter\n * @param path - Path adapter\n * @param itemPath - The path to calculate size for\n * @returns The size in bytes\n * @public\n */\nexport async function getDirectoryItemSize(\n  fs: FileSystemAdapter,\n  path: PathAdapter,\n  itemPath: string,\n): Promise<number> {\n  const stats = await fs.stat(itemPath)\n\n  if (!stats.isDirectory) {\n    return stats.size\n  }\n\n  let totalSize = 0\n  const entries = (await fs.readdir(itemPath, {\n    withFileTypes: true,\n  })) as DirectoryEntry[]\n\n  for (const entry of entries) {\n    const fullPath = path.join(itemPath, entry.name)\n    if (entry.isDirectory()) {\n      totalSize += await getDirectoryItemSize(fs, path, fullPath)\n    } else {\n      const fileStats = await fs.stat(fullPath)\n      totalSize += fileStats.size\n    }\n  }\n\n  return totalSize\n}\n\n/**\n * Search for files by name.\n * @param fs - FileSystem adapter\n * @param path - Path adapter\n * @param name - The name or partial name to search for\n * @param dir - The directory to search in\n * @returns Object containing arrays of paths and entries\n * @public\n */\nexport async function findFilesByName(\n  fs: FileSystemAdapter,\n  path: PathAdapter,\n  name: string,\n  dir: string,\n): Promise<{ paths: string[]; entries: DirectoryEntry[] }> {\n  const paths: string[] = []\n  const entries: DirectoryEntry[] = []\n\n  async function search(searchDir: string): Promise<void> {\n    try {\n      const items = (await fs.readdir(searchDir, {\n        withFileTypes: true,\n      })) as DirectoryEntry[]\n\n      for (const item of items) {\n        const fullPath = path.join(searchDir, item.name)\n\n        if (item.name.includes(name)) {\n          paths.push(fullPath)\n          entries.push(item)\n        }\n\n        if (item.isDirectory()) {\n          await search(fullPath)\n        }\n      }\n    } catch {\n      // Skip directories we can't access (e.g., permission denied)\n      // This allows the search to continue even when some directories are inaccessible\n    }\n  }\n\n  await search(dir)\n\n  return { paths, entries }\n}\n\n/**\n * Creates a new file.\n * @param fs - FileSystem adapter\n * @param name - The file path to create\n * @public\n */\nexport async function createFile(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<void> {\n  // Create an empty file by writing an empty string\n  await fs.writeFile(name, '')\n}\n\n/**\n * Creates a new directory.\n * Note: Parent directories must exist. Use recursive operations if you need to create nested directories.\n * @param fs - FileSystem adapter\n * @param name - The directory path to create\n * @public\n */\nexport async function createDirectory(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<void> {\n  const exists = await fs.exists(name)\n  if (!exists) {\n    await fs.mkdir(name, { recursive: false })\n  }\n}\n\n/**\n * Deletes a file.\n * @param fs - FileSystem adapter\n * @param name - The file path to delete\n * @public\n */\nexport async function deleteFile(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<void> {\n  await fs.unlink(name)\n}\n\n/**\n * Deletes a directory recursively.\n * @param fs - FileSystem adapter\n * @param name - The directory path to delete\n * @public\n */\nexport async function deleteDirectory(\n  fs: FileSystemAdapter,\n  name: string,\n): Promise<void> {\n  await fs.rmdir(name, { recursive: true, force: true })\n}\n\n/**\n * Renames a file or directory.\n * @param fs - FileSystem adapter\n * @param src - The source path\n * @param dst - The destination path\n * @public\n */\nexport async function renameDirectoryItem(\n  fs: FileSystemAdapter,\n  src: string,\n  dst: string,\n): Promise<void> {\n  await fs.rename(src, dst)\n}\n\n/**\n * Moves a file or directory.\n * @param fs - FileSystem adapter\n * @param src - The source path\n * @param dst - The destination path\n * @public\n */\nexport async function moveDirectoryItem(\n  fs: FileSystemAdapter,\n  src: string,\n  dst: string,\n): Promise<void> {\n  await fs.rename(src, dst)\n}\n\n/**\n * Copies a file with timestamp suffix.\n * @param fs - FileSystem adapter\n * @param path - Path adapter\n * @param name - The file path to copy\n * @returns The new file path\n * @public\n */\nexport async function copyFile(\n  fs: FileSystemAdapter,\n  path: PathAdapter,\n  name: string,\n): Promise<string> {\n  const output = generateTimestampedFilename(name, '', path)\n\n  await fs.copyFile(name, output)\n  return output\n}\n\n/**\n * Copies a directory recursively with timestamp suffix.\n * @param fs - FileSystem adapter\n * @param path - Path adapter\n * @param name - The directory path to copy\n * @returns The new directory path\n * @public\n */\nexport async function copyDirectory(\n  fs: FileSystemAdapter,\n  path: PathAdapter,\n  name: string,\n): Promise<string> {\n  const timestamp = Math.floor(Date.now() / 1000)\n  const output = `${name}_${timestamp}`\n\n  async function copyRecursive(src: string, dest: string): Promise<void> {\n    const stats = await fs.stat(src)\n\n    if (stats.isDirectory) {\n      await fs.mkdir(dest, { recursive: true })\n      const entries = (await fs.readdir(src, {\n        withFileTypes: true,\n      })) as DirectoryEntry[]\n\n      for (const entry of entries) {\n        const srcPath = path.join(src, entry.name)\n        const destPath = path.join(dest, entry.name)\n\n        if (entry.isDirectory()) {\n          await copyRecursive(srcPath, destPath)\n        } else {\n          await fs.copyFile(srcPath, destPath)\n        }\n      }\n    } else {\n      await fs.copyFile(src, dest)\n    }\n  }\n\n  await copyRecursive(name, output)\n  return output\n}\n\n/**\n * Writes content to a file.\n * @param fs - FileSystem adapter\n * @param filePath - The file path to write to\n * @param content - The content to write\n * @public\n */\nexport async function writeToFile(\n  fs: FileSystemAdapter,\n  filePath: string,\n  content: string,\n): Promise<void> {\n  await fs.writeFile(filePath, content)\n}\n"]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@boba-cli/filesystem",
+  "description": "Filesystem utility functions for Boba terminal UIs",
+  "version": "0.1.0-alpha.2",
+  "dependencies": {
+    "@boba-cli/machine": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "typescript": "5.8.2",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "check:api-report": "pnpm run generate:api-report",
+    "check:eslint": "pnpm run lint",
+    "generate:api-report": "api-extractor run --local",
+    "lint": "eslint \"{src,test}/**/*.{ts,tsx}\"",
+    "test": "vitest run"
+  }
+}