Feature/updown

README.md

@@ -59,6 +59,7 @@ Requirements:
 - Filesystem operations across core modules.
 - Mount support with scheme paths (`name://path`) and default filesystem support for relative paths.
 - Config-driven storage bootstrap via `StorageFactory` for local/custom/adapter-based filesystems.
+- Unified entry facade via `Infocyph\Pathwise\File` for file/dir/processors/storage/tooling.
 - Advanced file APIs: checksum verification, visibility controls, URL passthrough (`publicUrl`, `temporaryUrl`).
 - Directory automation: sync with diff report, recursive copy/move/delete, mounted-path ZIP/unzip bridging.
 - Upload/download pipelines: chunked/resumable uploads, validation profiles (image/video/document), extension allow/deny controls, strict MIME/signature checks, upload-id safety validation, malware-scan hook, secure download metadata + range handling.
@@ -137,6 +138,22 @@ StorageFactory::mount('tenant', [
 ]);
 ```
 
+## **Unified File Facade**
+
+Use a single entry point when you want fewer direct class imports.
+
+```php
+use Infocyph\Pathwise\File;
+
+$entry = File::at('/tmp/example.txt');
+$entry->file()->create('hello')->append("\nworld");
+
+$upload = File::upload();
+$download = File::download();
+
+File::mountStorage('assets', ['driver' => 'local', 'root' => '/srv/assets']);
+```
+
 ## **FileManager**
 
 The `FileManager` module provides classes for handling files, including reading, writing, compressing and general file operations.

docs/capabilities.rst

@@ -14,6 +14,21 @@ Pathwise combines two layers:
 Primary Modules
 ---------------
 
+Unified Facade (``Infocyph\Pathwise\File``)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Class:
+
+* ``File``
+
+What you get:
+
+* One path-bound entry to ``FileOperations``, ``DirectoryOperations``,
+  ``SafeFileReader``, ``SafeFileWriter`` and ``FileCompression``.
+* Static gateways for ``UploadProcessor``, ``DownloadProcessor``,
+  ``StorageFactory``, ``PolicyEngine``, ``FileJobQueue``, ``AuditTrail``,
+  ``RetentionManager``, ``ChecksumIndexer`` and ``FileWatcher``.
+
 File IO (``Infocyph\Pathwise\FileManager``)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -122,5 +137,6 @@ Optional:
 What to Read Next
 -----------------
 
+* ``file-facade`` for unified usage style.
 * ``quickstart`` for first-use examples.
 * ``recipes`` for end-to-end flows.

docs/file-facade.rst

@@ -0,0 +1,97 @@
+Unified File Facade
+===================
+
+Namespace: ``Infocyph\Pathwise``
+
+Pathwise provides ``File`` as a convenience facade when you want one entry
+point instead of importing many classes directly.
+
+Use this when:
+
+* you want path-bound access to file/directory/compression/read/write APIs
+* you want static gateways for upload/download/storage/policy/queue/audit/etc.
+
+Keep direct classes when:
+
+* you prefer explicit class-level imports for large codebases
+* you need very focused dependencies per module
+
+Path-Bound Access
+-----------------
+
+.. code-block:: php
+
+   use Infocyph\Pathwise\File;
+
+   $entry = File::at('/tmp/demo.txt');
+
+   $entry->file()->create('hello')->append("\nworld");
+
+   $reader = $entry->reader();
+   foreach ($reader->line() as $line) {
+       // ...
+   }
+
+   $writer = $entry->writer(true);
+   $writer->line('tail');
+   $writer->close();
+
+   $metadata = $entry->metadata();
+
+Directory + Compression via Same Entry
+--------------------------------------
+
+.. code-block:: php
+
+   use Infocyph\Pathwise\File;
+
+   File::at('/tmp/source')->directory()->create();
+
+   File::at('/tmp/archive.zip')
+       ->compression(true)
+       ->compress('/tmp/source')
+       ->save();
+
+Static Gateways
+---------------
+
+.. code-block:: php
+
+   use Infocyph\Pathwise\File;
+
+   $upload = File::upload();
+   $download = File::download();
+   $policy = File::policy();
+   $queue = File::queue('/tmp/jobs.json');
+   $audit = File::audit('/tmp/audit.jsonl');
+
+Storage from Facade
+-------------------
+
+``File`` delegates storage creation/mounting to ``StorageFactory``.
+
+.. code-block:: php
+
+   use Infocyph\Pathwise\File;
+
+   File::mountStorage('assets', [
+       'driver' => 'local',
+       'root' => '/srv/storage/assets',
+   ]);
+
+   // For other adapters, pass adapter/constructor config:
+   // File::mountStorage('s3', ['driver' => 's3', 'adapter' => $adapter]);
+
+Operational Tooling from Facade
+-------------------------------
+
+Available helpers:
+
+* ``File::retain(...)`` -> ``RetentionManager``
+* ``File::index(...)`` / ``File::duplicates(...)`` / ``File::deduplicate(...)`` -> ``ChecksumIndexer``
+* ``File::snapshot(...)`` / ``File::diffSnapshots(...)`` / ``File::watch(...)`` -> ``FileWatcher``
+
+See also:
+
+* ``storage-adapters`` for adapter bootstrap
+* ``upload-processing`` and ``download-processing`` for stream workflows

docs/index.rst

@@ -13,6 +13,7 @@ queue/audit tooling, and operational helpers.
    installation
    capabilities
    storage-adapters
+   file-facade
    quickstart
    recipes
    file-manager

docs/installation.rst

@@ -41,12 +41,12 @@ See ``storage-adapters`` for setup patterns.
 Where to Use First
 ------------------
 
-If you are evaluating Pathwise, start with ``FileOperations`` and
-``DirectoryOperations``. They cover the largest set of day-to-day file tasks.
+If you are evaluating Pathwise, start with the unified ``File`` facade, then
+drop down to direct module classes as needed.
 
 .. code-block:: php
 
-   use Infocyph\Pathwise\FileManager\FileOperations;
+   use Infocyph\Pathwise\File;
 
-   $ops = new FileOperations('/tmp/example.txt');
+   $ops = File::at('/tmp/example.txt')->file();
    $ops->create('initial')->update('updated');

docs/overview.rst

@@ -15,6 +15,7 @@ It focuses on three layers:
 
 Main namespaces:
 
+* ``Infocyph\Pathwise`` (unified ``File`` facade)
 * ``Infocyph\Pathwise\FileManager``
 * ``Infocyph\Pathwise\DirectoryManager``
 * ``Infocyph\Pathwise\StreamHandler``
@@ -36,19 +37,21 @@ Quick Start
 
 .. code-block:: php
 
-   use Infocyph\Pathwise\FileManager\FileOperations;
-   use Infocyph\Pathwise\DirectoryManager\DirectoryOperations;
+   use Infocyph\Pathwise\File;
 
-   (new FileOperations('/tmp/demo.txt'))
+   File::at('/tmp/demo.txt')
+       ->file()
        ->create('hello')
        ->append("\nworld");
 
-   $report = (new DirectoryOperations('/tmp/source'))
+   $report = File::at('/tmp/source')
+       ->directory()
        ->syncTo('/tmp/backup', deleteOrphans: true);
 
 Read Next
 ---------
 
 * ``capabilities`` for the full module map.
+* ``file-facade`` for the unified entry style.
 * ``quickstart`` for copy/paste examples.
 * ``recipes`` for end-to-end workflow patterns.

docs/quickstart.rst

@@ -15,9 +15,9 @@ This quickstart shows the fastest way to understand what Pathwise can do.
 
 .. code-block:: php
 
-   use Infocyph\Pathwise\FileManager\FileOperations;
+   use Infocyph\Pathwise\File;
 
-   $file = new FileOperations('/tmp/example.txt');
+   $file = File::at('/tmp/example.txt')->file();
    $file->create("v1\n")
        ->append("v2\n")
        ->writeAndVerify("v3\n", 'sha256');

src/DirectoryManager/DirectoryOperations.php

@@ -303,6 +303,12 @@ public function listContents(bool $detailed = false, ?callable $filter = null):
         return $contents;
     }
 
+    /**
+     * List directory contents as a DirectoryListing object.
+     *
+     * @param bool $deep Whether to list contents recursively. Defaults to true.
+     * @return DirectoryListing The directory listing.
+     */
     public function listContentsListing(bool $deep = true): DirectoryListing
     {
         return FlysystemHelper::listContentsListing($this->path, $deep);
@@ -363,6 +369,12 @@ public function move(string $destination): bool
         return true;
     }
 
+    /**
+     * Set the execution strategy for directory operations.
+     *
+     * @param ExecutionStrategy $executionStrategy The execution strategy to use.
+     * @return self This instance for method chaining.
+     */
     public function setExecutionStrategy(ExecutionStrategy $executionStrategy): self
     {
         $this->executionStrategy = $executionStrategy;
@@ -385,6 +397,12 @@ public function setPermissions(int $permissions): bool
         return chmod($this->path, $permissions);
     }
 
+    /**
+     * Set the visibility of the directory.
+     *
+     * @param string $visibility The visibility to set (e.g., 'public' or 'private').
+     * @return self This instance for method chaining.
+     */
     public function setVisibility(string $visibility): self
     {
         FlysystemHelper::setVisibility($this->path, $visibility);
@@ -486,6 +504,12 @@ public function unzip(string $source): bool
         }
     }
 
+    /**
+     * Get the visibility of the directory.
+     *
+     * @return string|null The visibility, or null if not available.
+     * @throws DirectoryOperationException If the directory does not exist.
+     */
     public function visibility(): ?string
     {
         if (!FlysystemHelper::directoryExists($this->path)) {