@molecule/app-filesystem 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Device filesystem access interface for molecule.dev.
+ *
+ * Framework-agnostic core for app-scoped file storage through a swappable
+ * `FilesystemProvider`: read/write/append (text or Blob), directories
+ * (mkdir/rmdir/readdir), stat/exists, copy/move, URIs for native viewers,
+ * and free-space checks — all addressed relative to well-known base
+ * directories (`'documents' | 'data' | 'cache' | 'external' | 'library' |
+ * 'temp'`). Pure path/format helpers (`joinPath`, `getExtension`,
+ * `getBasename`, `getDirname`, `getMimeType`, `formatFileSize`) work
+ * without a provider.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   exists,
+ *   hasProvider,
+ *   joinPath,
+ *   readFile,
+ *   writeFile,
+ * } from '@molecule/app-filesystem'
+ *
+ * async function saveDraft(text: string): Promise<void> {
+ *   if (!hasProvider()) return // no provider wired — use app-storage instead
+ *   const path = joinPath('drafts', 'note.txt')
+ *   await writeFile(path, text, { directory: 'data', recursive: true })
+ * }
+ *
+ * async function loadDraft(): Promise<string | null> {
+ *   const path = joinPath('drafts', 'note.txt')
+ *   if (!(await exists(path, { directory: 'data' }))) return null
+ *   return readFile(path, { directory: 'data' })
+ * }
+ * ```
+ *
+ * @remarks
+ * - **Every file operation THROWS until `setProvider()` is called** — there
+ *   is no web fallback and **no prebuilt provider package ships with
+ *   molecule**; supply a `FilesystemProvider` from your native runtime.
+ * - **This is NOT general key-value persistence.** For settings/state on any
+ *   platform use `@molecule/app-storage`; reach for app-filesystem only when
+ *   you genuinely need files (large blobs, exports, media handed to other
+ *   apps via `getUri`).
+ * - On web there is no path-addressed filesystem; a provider could be built
+ *   on OPFS (origin-private, invisible to the user's file manager), but
+ *   `'external'`/`'library'` semantics and `getUri` for OS viewers do not
+ *   translate — feature-gate on `getCapabilities()`.
+ * - Paths are RELATIVE to the `directory` base option (default varies by
+ *   provider — pass it explicitly). Use `joinPath`, never string-concat
+ *   with `/`.
+ * - Write ops fail on missing parent directories unless
+ *   `{ recursive: true }`.
+ *
+ * @module
+ */
+export * from './provider.js';
+export * from './types.js';
+export * from './utilities.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,59 @@
+/**
+ * Device filesystem access interface for molecule.dev.
+ *
+ * Framework-agnostic core for app-scoped file storage through a swappable
+ * `FilesystemProvider`: read/write/append (text or Blob), directories
+ * (mkdir/rmdir/readdir), stat/exists, copy/move, URIs for native viewers,
+ * and free-space checks — all addressed relative to well-known base
+ * directories (`'documents' | 'data' | 'cache' | 'external' | 'library' |
+ * 'temp'`). Pure path/format helpers (`joinPath`, `getExtension`,
+ * `getBasename`, `getDirname`, `getMimeType`, `formatFileSize`) work
+ * without a provider.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   exists,
+ *   hasProvider,
+ *   joinPath,
+ *   readFile,
+ *   writeFile,
+ * } from '@molecule/app-filesystem'
+ *
+ * async function saveDraft(text: string): Promise<void> {
+ *   if (!hasProvider()) return // no provider wired — use app-storage instead
+ *   const path = joinPath('drafts', 'note.txt')
+ *   await writeFile(path, text, { directory: 'data', recursive: true })
+ * }
+ *
+ * async function loadDraft(): Promise<string | null> {
+ *   const path = joinPath('drafts', 'note.txt')
+ *   if (!(await exists(path, { directory: 'data' }))) return null
+ *   return readFile(path, { directory: 'data' })
+ * }
+ * ```
+ *
+ * @remarks
+ * - **Every file operation THROWS until `setProvider()` is called** — there
+ *   is no web fallback and **no prebuilt provider package ships with
+ *   molecule**; supply a `FilesystemProvider` from your native runtime.
+ * - **This is NOT general key-value persistence.** For settings/state on any
+ *   platform use `@molecule/app-storage`; reach for app-filesystem only when
+ *   you genuinely need files (large blobs, exports, media handed to other
+ *   apps via `getUri`).
+ * - On web there is no path-addressed filesystem; a provider could be built
+ *   on OPFS (origin-private, invisible to the user's file manager), but
+ *   `'external'`/`'library'` semantics and `getUri` for OS viewers do not
+ *   translate — feature-gate on `getCapabilities()`.
+ * - Paths are RELATIVE to the `directory` base option (default varies by
+ *   provider — pass it explicitly). Use `joinPath`, never string-concat
+ *   with `/`.
+ * - Write ops fail on missing parent directories unless
+ *   `{ recursive: true }`.
+ *
+ * @module
+ */
+export * from './provider.js';
+export * from './types.js';
+export * from './utilities.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Filesystem provider management for molecule.dev.
+ *
+ * @module
+ */
+import type { CopyOptions, DeleteOptions, Directory, FileInfo, FilesystemCapabilities, FilesystemProvider, ListOptions, ReadOptions, StatOptions, WriteOptions } from './types.js';
+/**
+ * Set the filesystem provider.
+ * @param provider - FilesystemProvider implementation to register.
+ */
+export declare function setProvider(provider: FilesystemProvider): void;
+/**
+ * Get the current filesystem provider.
+ * @throws {Error} If no provider has been set via setProvider.
+ * @returns The active FilesystemProvider instance.
+ */
+export declare function getProvider(): FilesystemProvider;
+/**
+ * Check if a filesystem provider has been registered.
+ * @returns Whether a FilesystemProvider has been bonded.
+ */
+export declare function hasProvider(): boolean;
+/**
+ * Read a file as text.
+ * @param path - The file path to read.
+ * @param options - Read options (directory, encoding).
+ * @returns The file contents as a string.
+ */
+export declare function readFile(path: string, options?: ReadOptions): Promise<string>;
+/**
+ * Read a file as binary data.
+ * @param path - The file path to read.
+ * @param options - Read options (directory).
+ * @returns The file contents as a Blob.
+ */
+export declare function readFileAsBlob(path: string, options?: Omit<ReadOptions, 'encoding'>): Promise<Blob>;
+/**
+ * Write text content to a file.
+ * @param path - The file path to write to.
+ * @param data - The text content to write.
+ * @param options - Write options (directory, encoding, recursive, append).
+ * @returns A promise that resolves when the file is written.
+ */
+export declare function writeFile(path: string, data: string, options?: WriteOptions): Promise<void>;
+/**
+ * Write binary data to a file.
+ * @param path - The file path to write to.
+ * @param data - The binary data to write as a Blob.
+ * @param options - Write options (directory, recursive).
+ * @returns A promise that resolves when the file is written.
+ */
+export declare function writeFileFromBlob(path: string, data: Blob, options?: Omit<WriteOptions, 'encoding'>): Promise<void>;
+/**
+ * Append text content to a file.
+ * @param path - The file path to append to.
+ * @param data - The text content to append.
+ * @param options - Write options (directory, encoding).
+ * @returns A promise that resolves when the data is appended.
+ */
+export declare function appendFile(path: string, data: string, options?: WriteOptions): Promise<void>;
+/**
+ * Delete a file.
+ * @param path - The file path to delete.
+ * @param options - Delete options (directory, recursive).
+ * @returns A promise that resolves when the file is deleted.
+ */
+export declare function deleteFile(path: string, options?: DeleteOptions): Promise<void>;
+/**
+ * Create a directory.
+ * @param path - The directory path to create.
+ * @param options - Write options (directory, recursive for parent directories).
+ * @returns A promise that resolves when the directory is created.
+ */
+export declare function mkdir(path: string, options?: WriteOptions): Promise<void>;
+/**
+ * Remove a directory.
+ * @param path - The directory path to remove.
+ * @param options - Delete options (directory, recursive for contents).
+ * @returns A promise that resolves when the directory is removed.
+ */
+export declare function rmdir(path: string, options?: DeleteOptions): Promise<void>;
+/**
+ * List directory contents.
+ * @param path - The directory path to list.
+ * @param options - List options (directory, include hidden files).
+ * @returns An array of FileInfo objects for each entry.
+ */
+export declare function readdir(path: string, options?: ListOptions): Promise<FileInfo[]>;
+/**
+ * Get file or directory metadata.
+ * @param path - The path to stat.
+ * @param options - Stat options (directory).
+ * @returns The FileInfo with size, dates, and type information.
+ */
+export declare function stat(path: string, options?: StatOptions): Promise<FileInfo>;
+/**
+ * Check if a file or directory exists.
+ * @param path - The path to check.
+ * @param options - Stat options (directory).
+ * @returns Whether the path exists.
+ */
+export declare function exists(path: string, options?: StatOptions): Promise<boolean>;
+/**
+ * Copy a file to a new location.
+ * @param from - The source file path.
+ * @param to - The destination file path.
+ * @param options - Copy options (source/dest directories, overwrite).
+ * @returns A promise that resolves when the file is copied.
+ */
+export declare function copy(from: string, to: string, options?: CopyOptions): Promise<void>;
+/**
+ * Move or rename a file.
+ * @param from - The source file path.
+ * @param to - The destination file path.
+ * @param options - Move options (source/dest directories, overwrite).
+ * @returns A promise that resolves when the file is moved.
+ */
+export declare function move(from: string, to: string, options?: CopyOptions): Promise<void>;
+/**
+ * Get the platform-specific URI for a file path.
+ * @param path - The file path to resolve.
+ * @param options - Stat options (directory).
+ * @returns The file's platform URI string.
+ */
+export declare function getUri(path: string, options?: StatOptions): Promise<string>;
+/**
+ * Get available storage space in bytes for a directory.
+ * @param directory - The directory type to check (defaults to app data).
+ * @returns The available space in bytes.
+ */
+export declare function getAvailableSpace(directory?: Directory): Promise<number>;
+/**
+ * Get the platform's filesystem capabilities.
+ * @returns The capabilities indicating available directories, picker support, and size limits.
+ */
+export declare function getCapabilities(): Promise<FilesystemCapabilities>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/provider.js

@@ -0,0 +1,186 @@
+/**
+ * Filesystem provider management for molecule.dev.
+ *
+ * @module
+ */
+import { bond, get as bondGet, isBonded } from '@molecule/app-bond';
+import { t } from '@molecule/app-i18n';
+const BOND_TYPE = 'filesystem';
+/**
+ * Set the filesystem provider.
+ * @param provider - FilesystemProvider implementation to register.
+ */
+export function setProvider(provider) {
+    bond(BOND_TYPE, provider);
+}
+/**
+ * Get the current filesystem provider.
+ * @throws {Error} If no provider has been set via setProvider.
+ * @returns The active FilesystemProvider instance.
+ */
+export function getProvider() {
+    const provider = bondGet(BOND_TYPE);
+    if (!provider) {
+        throw new Error(t('filesystem.error.noProvider', undefined, {
+            defaultValue: '@molecule/app-filesystem: No provider set. Call setProvider() with a FilesystemProvider implementation — no provider ships with the fleet; implement the interface on your native runtime and bond it.',
+        }));
+    }
+    return provider;
+}
+/**
+ * Check if a filesystem provider has been registered.
+ * @returns Whether a FilesystemProvider has been bonded.
+ */
+export function hasProvider() {
+    return isBonded(BOND_TYPE);
+}
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+/**
+ * Read a file as text.
+ * @param path - The file path to read.
+ * @param options - Read options (directory, encoding).
+ * @returns The file contents as a string.
+ */
+export async function readFile(path, options) {
+    return getProvider().readFile(path, options);
+}
+/**
+ * Read a file as binary data.
+ * @param path - The file path to read.
+ * @param options - Read options (directory).
+ * @returns The file contents as a Blob.
+ */
+export async function readFileAsBlob(path, options) {
+    return getProvider().readFileAsBlob(path, options);
+}
+/**
+ * Write text content to a file.
+ * @param path - The file path to write to.
+ * @param data - The text content to write.
+ * @param options - Write options (directory, encoding, recursive, append).
+ * @returns A promise that resolves when the file is written.
+ */
+export async function writeFile(path, data, options) {
+    return getProvider().writeFile(path, data, options);
+}
+/**
+ * Write binary data to a file.
+ * @param path - The file path to write to.
+ * @param data - The binary data to write as a Blob.
+ * @param options - Write options (directory, recursive).
+ * @returns A promise that resolves when the file is written.
+ */
+export async function writeFileFromBlob(path, data, options) {
+    return getProvider().writeFileFromBlob(path, data, options);
+}
+/**
+ * Append text content to a file.
+ * @param path - The file path to append to.
+ * @param data - The text content to append.
+ * @param options - Write options (directory, encoding).
+ * @returns A promise that resolves when the data is appended.
+ */
+export async function appendFile(path, data, options) {
+    return getProvider().appendFile(path, data, options);
+}
+/**
+ * Delete a file.
+ * @param path - The file path to delete.
+ * @param options - Delete options (directory, recursive).
+ * @returns A promise that resolves when the file is deleted.
+ */
+export async function deleteFile(path, options) {
+    return getProvider().deleteFile(path, options);
+}
+/**
+ * Create a directory.
+ * @param path - The directory path to create.
+ * @param options - Write options (directory, recursive for parent directories).
+ * @returns A promise that resolves when the directory is created.
+ */
+export async function mkdir(path, options) {
+    return getProvider().mkdir(path, options);
+}
+/**
+ * Remove a directory.
+ * @param path - The directory path to remove.
+ * @param options - Delete options (directory, recursive for contents).
+ * @returns A promise that resolves when the directory is removed.
+ */
+export async function rmdir(path, options) {
+    return getProvider().rmdir(path, options);
+}
+/**
+ * List directory contents.
+ * @param path - The directory path to list.
+ * @param options - List options (directory, include hidden files).
+ * @returns An array of FileInfo objects for each entry.
+ */
+export async function readdir(path, options) {
+    return getProvider().readdir(path, options);
+}
+/**
+ * Get file or directory metadata.
+ * @param path - The path to stat.
+ * @param options - Stat options (directory).
+ * @returns The FileInfo with size, dates, and type information.
+ */
+export async function stat(path, options) {
+    return getProvider().stat(path, options);
+}
+/**
+ * Check if a file or directory exists.
+ * @param path - The path to check.
+ * @param options - Stat options (directory).
+ * @returns Whether the path exists.
+ */
+export async function exists(path, options) {
+    return getProvider().exists(path, options);
+}
+/**
+ * Copy a file to a new location.
+ * @param from - The source file path.
+ * @param to - The destination file path.
+ * @param options - Copy options (source/dest directories, overwrite).
+ * @returns A promise that resolves when the file is copied.
+ */
+export async function copy(from, to, options) {
+    return getProvider().copy(from, to, options);
+}
+/**
+ * Move or rename a file.
+ * @param from - The source file path.
+ * @param to - The destination file path.
+ * @param options - Move options (source/dest directories, overwrite).
+ * @returns A promise that resolves when the file is moved.
+ */
+export async function move(from, to, options) {
+    return getProvider().move(from, to, options);
+}
+/**
+ * Get the platform-specific URI for a file path.
+ * @param path - The file path to resolve.
+ * @param options - Stat options (directory).
+ * @returns The file's platform URI string.
+ */
+export async function getUri(path, options) {
+    return getProvider().getUri(path, options);
+}
+/**
+ * Get available storage space in bytes for a directory.
+ * @param directory - The directory type to check (defaults to app data).
+ * @returns The available space in bytes.
+ */
+export async function getAvailableSpace(directory) {
+    return getProvider().getAvailableSpace(directory);
+}
+/**
+ * Get the platform's filesystem capabilities.
+ * @returns The capabilities indicating available directories, picker support, and size limits.
+ */
+export async function getCapabilities() {
+    return getProvider().getCapabilities();
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Filesystem types for molecule.dev.
+ *
+ * @module
+ */
+/**
+ * File system directory type
+ */
+export type Directory = 'documents' | 'data' | 'cache' | 'external' | 'library' | 'temp';
+/**
+ * Text encoding for file read/write operations.
+ */
+export type Encoding = 'utf8' | 'ascii' | 'base64';
+/**
+ * Metadata about a file or directory (name, path, size, timestamps, type).
+ */
+export interface FileInfo {
+    /** File name */
+    name: string;
+    /** Full path */
+    path: string;
+    /** File URI */
+    uri: string;
+    /** File size in bytes */
+    size: number;
+    /** Creation time (ISO string) */
+    createdAt?: string;
+    /** Modification time (ISO string) */
+    modifiedAt?: string;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+    /** Whether this is a file */
+    isFile: boolean;
+    /** MIME type (if available) */
+    mimeType?: string;
+}
+/**
+ * Options for reading a file (target directory and text encoding).
+ */
+export interface ReadOptions {
+    /** Directory to read from */
+    directory?: Directory;
+    /** File encoding */
+    encoding?: Encoding;
+}
+/**
+ * Options for writing a file (directory, encoding, recursive creation, append mode).
+ */
+export interface WriteOptions {
+    /** Directory to write to */
+    directory?: Directory;
+    /** File encoding */
+    encoding?: Encoding;
+    /** Whether to create parent directories */
+    recursive?: boolean;
+    /** Whether to append to existing file */
+    append?: boolean;
+}
+/**
+ * Copy/move options
+ */
+export interface CopyOptions {
+    /** Source directory */
+    fromDirectory?: Directory;
+    /** Destination directory */
+    toDirectory?: Directory;
+    /** Overwrite existing file */
+    overwrite?: boolean;
+}
+/**
+ * Options for listing directory contents (directory type, hidden files).
+ */
+export interface ListOptions {
+    /** Directory type */
+    directory?: Directory;
+    /** Whether to include hidden files */
+    includeHidden?: boolean;
+}
+/**
+ * Options for getting file/directory metadata (target directory type).
+ */
+export interface StatOptions {
+    /** Directory type */
+    directory?: Directory;
+}
+/**
+ * Options for deleting a file or directory (directory type, recursive deletion).
+ */
+export interface DeleteOptions {
+    /** Directory type */
+    directory?: Directory;
+    /** Delete directory contents recursively */
+    recursive?: boolean;
+}
+/**
+ * Filesystem capabilities
+ */
+export interface FilesystemCapabilities {
+    /** Whether filesystem access is supported */
+    supported: boolean;
+    /** Available directories */
+    directories: Directory[];
+    /** Whether external storage is available */
+    hasExternalStorage: boolean;
+    /** Whether file picking is supported */
+    hasPicker: boolean;
+    /** Maximum file size (if limited) */
+    maxFileSize?: number;
+}
+/**
+ * Filesystem provider interface
+ */
+export interface FilesystemProvider {
+    /**
+     * Read a file as text
+     * @param path - File path
+     * @param options - Read options
+     */
+    readFile(path: string, options?: ReadOptions): Promise<string>;
+    /**
+     * Read a file as binary data
+     * @param path - File path
+     * @param options - Read options
+     */
+    readFileAsBlob(path: string, options?: Omit<ReadOptions, 'encoding'>): Promise<Blob>;
+    /**
+     * Write text to a file
+     * @param path - File path
+     * @param data - Content to write
+     * @param options - Write options
+     */
+    writeFile(path: string, data: string, options?: WriteOptions): Promise<void>;
+    /**
+     * Write binary data to a file
+     * @param path - File path
+     * @param data - Binary data to write
+     * @param options - Write options
+     */
+    writeFileFromBlob(path: string, data: Blob, options?: Omit<WriteOptions, 'encoding'>): Promise<void>;
+    /**
+     * Append text to a file
+     * @param path - File path
+     * @param data - Content to append
+     * @param options - Write options
+     */
+    appendFile(path: string, data: string, options?: WriteOptions): Promise<void>;
+    /**
+     * Delete a file
+     * @param path - File path
+     * @param options - Delete options
+     */
+    deleteFile(path: string, options?: DeleteOptions): Promise<void>;
+    /**
+     * Create a directory
+     * @param path - Directory path
+     * @param options - Options
+     */
+    mkdir(path: string, options?: WriteOptions): Promise<void>;
+    /**
+     * Remove a directory
+     * @param path - Directory path
+     * @param options - Delete options
+     */
+    rmdir(path: string, options?: DeleteOptions): Promise<void>;
+    /**
+     * List directory contents
+     * @param path - Directory path
+     * @param options - List options
+     */
+    readdir(path: string, options?: ListOptions): Promise<FileInfo[]>;
+    /**
+     * Get file/directory info
+     * @param path - Path
+     * @param options - Stat options
+     */
+    stat(path: string, options?: StatOptions): Promise<FileInfo>;
+    /**
+     * Check if file/directory exists
+     * @param path - Path
+     * @param options - Options
+     */
+    exists(path: string, options?: StatOptions): Promise<boolean>;
+    /**
+     * Copy a file
+     * @param from - Source path
+     * @param to - Destination path
+     * @param options - Copy options
+     */
+    copy(from: string, to: string, options?: CopyOptions): Promise<void>;
+    /**
+     * Move/rename a file
+     * @param from - Source path
+     * @param to - Destination path
+     * @param options - Copy options
+     */
+    move(from: string, to: string, options?: CopyOptions): Promise<void>;
+    /**
+     * Get the platform URI for a file path.
+     * @param path - The file path to resolve.
+     * @param options - Options including directory type.
+     * @returns The file's platform-specific URI string.
+     */
+    getUri(path: string, options?: StatOptions): Promise<string>;
+    /**
+     * Get available storage space in bytes.
+     * @param directory - The directory type to check (defaults to app data).
+     * @returns The available space in bytes.
+     */
+    getAvailableSpace(directory?: Directory): Promise<number>;
+    /**
+     * Get the platform's filesystem capabilities.
+     * @returns The capabilities indicating available directories, picker support, and size limits.
+     */
+    getCapabilities(): Promise<FilesystemCapabilities>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Filesystem types for molecule.dev.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/utilities.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Filesystem utility functions for molecule.dev.
+ *
+ * @module
+ */
+/**
+ * Format a byte count as a human-readable file size string (e.g., '1.5 MB').
+ * @param bytes - The size in bytes.
+ * @returns A formatted string with the appropriate unit (B, KB, MB, GB, TB).
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Extract the file extension from a path, without the leading dot.
+ * @param path - The file path or filename.
+ * @returns The lowercase extension (e.g., 'txt'), or empty string if none.
+ */
+export declare function getExtension(path: string): string;
+/**
+ * Get the filename without its extension from a path.
+ * @param path - The file path.
+ * @returns The base filename without extension (e.g., 'readme' from '/docs/readme.md').
+ */
+export declare function getBasename(path: string): string;
+/**
+ * Get the directory portion of a file path.
+ * @param path - The file path.
+ * @returns The parent directory path (e.g., '/docs' from '/docs/readme.md').
+ */
+export declare function getDirname(path: string): string;
+/**
+ * Join multiple path segments into a single normalized path.
+ * Collapses duplicate slashes and removes trailing slashes.
+ * @param segments - The path segments to join.
+ * @returns The joined and normalized path.
+ */
+export declare function joinPath(...segments: string[]): string;
+/**
+ * Infer a MIME type from a file extension. Supports common image, document,
+ * text, media, and archive formats. Falls back to 'application/octet-stream'.
+ * @param path - The file path or extension to look up.
+ * @returns The inferred MIME type string.
+ */
+export declare function getMimeType(path: string): string;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWpD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwChD"}

package/dist/utilities.js

@@ -0,0 +1,106 @@
+/**
+ * Filesystem utility functions for molecule.dev.
+ *
+ * @module
+ */
+/**
+ * Format a byte count as a human-readable file size string (e.g., '1.5 MB').
+ * @param bytes - The size in bytes.
+ * @returns A formatted string with the appropriate unit (B, KB, MB, GB, TB).
+ */
+export function formatFileSize(bytes) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let unitIndex = 0;
+    let size = bytes;
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+    return `${size.toFixed(unitIndex > 0 ? 1 : 0)} ${units[unitIndex]}`;
+}
+/**
+ * Extract the file extension from a path, without the leading dot.
+ * @param path - The file path or filename.
+ * @returns The lowercase extension (e.g., 'txt'), or empty string if none.
+ */
+export function getExtension(path) {
+    const parts = path.split('.');
+    return parts.length > 1 ? parts.pop().toLowerCase() : '';
+}
+/**
+ * Get the filename without its extension from a path.
+ * @param path - The file path.
+ * @returns The base filename without extension (e.g., 'readme' from '/docs/readme.md').
+ */
+export function getBasename(path) {
+    const name = path.split('/').pop() || '';
+    const dotIndex = name.lastIndexOf('.');
+    return dotIndex > 0 ? name.slice(0, dotIndex) : name;
+}
+/**
+ * Get the directory portion of a file path.
+ * @param path - The file path.
+ * @returns The parent directory path (e.g., '/docs' from '/docs/readme.md').
+ */
+export function getDirname(path) {
+    const parts = path.split('/');
+    parts.pop();
+    return parts.join('/') || '/';
+}
+/**
+ * Join multiple path segments into a single normalized path.
+ * Collapses duplicate slashes and removes trailing slashes.
+ * @param segments - The path segments to join.
+ * @returns The joined and normalized path.
+ */
+export function joinPath(...segments) {
+    return segments.join('/').replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+}
+/**
+ * Infer a MIME type from a file extension. Supports common image, document,
+ * text, media, and archive formats. Falls back to 'application/octet-stream'.
+ * @param path - The file path or extension to look up.
+ * @returns The inferred MIME type string.
+ */
+export function getMimeType(path) {
+    const ext = getExtension(path);
+    const mimeTypes = {
+        // Images
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        png: 'image/png',
+        gif: 'image/gif',
+        webp: 'image/webp',
+        svg: 'image/svg+xml',
+        // Documents
+        pdf: 'application/pdf',
+        doc: 'application/msword',
+        docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        xls: 'application/vnd.ms-excel',
+        xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        ppt: 'application/vnd.ms-powerpoint',
+        pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        // Text
+        txt: 'text/plain',
+        csv: 'text/csv',
+        json: 'application/json',
+        xml: 'application/xml',
+        html: 'text/html',
+        css: 'text/css',
+        js: 'application/javascript',
+        ts: 'text/typescript',
+        // Media
+        mp3: 'audio/mpeg',
+        wav: 'audio/wav',
+        ogg: 'audio/ogg',
+        mp4: 'video/mp4',
+        webm: 'video/webm',
+        mov: 'video/quicktime',
+        // Archives
+        zip: 'application/zip',
+        tar: 'application/x-tar',
+        gz: 'application/gzip',
+    };
+    return mimeTypes[ext] || 'application/octet-stream';
+}
+//# sourceMappingURL=utilities.js.map

package/dist/utilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@molecule/app-filesystem",
+  "version": "1.0.0",
+  "description": "Device filesystem access interface for molecule.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "filesystem",
+    "files",
+    "storage",
+    "native"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/app-bond": "^1.0.0",
+    "@molecule/app-i18n": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/app-bond": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/app/native/filesystem"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/app/native/filesystem",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}