Merge https://github.com/apache/cordova-plugin-file into electron3

Author: pjoriginal

.asf.yaml

@@ -15,6 +15,32 @@
 # specific language governing permissions and limitations
 # under the License.
 
+github:
+  description: Apache Cordova File Plugin
+  homepage: https://cordova.apache.org/
+
+  labels:
+    - android
+    - cordova
+    - hacktoberfest
+    - ios
+    - java
+    - javascript
+    - library
+    - mobile
+    - nodejs
+    - objective-c
+
+  features:
+    wiki: false
+    issues: true
+    projects: true
+
+  enabled_merge_buttons:
+    squash: true
+    merge: false
+    rebase: false
+
 notifications:
   commits:              [email protected]
   issues:               [email protected]

.github/workflows/android.yml

@@ -57,8 +57,8 @@ jobs:
       matrix:
         versions:
           # Test the lowest minimum supported APIs
-          - android: 5.1
-            android-api: 22
+          - android: 7
+            android-api: 24
 
           # Test the last 3-4 supported APIs
           - android: 10
@@ -67,12 +67,12 @@ jobs:
           - android: 11
             android-api: 30
 
-          - android: 12
-            android-api: 31
-
           - android: 12L
             android-api: 32
 
+          - android: 13
+            android-api: 33
+
     timeout-minutes: 60
 
     steps:
@@ -105,7 +105,7 @@ jobs:
         if: ${{ endswith(env.repo, '/cordova-paramedic') != true }}
         run: npm i -g github:apache/cordova-paramedic
 
-      - uses: reactivecircus/android-emulator-runner@5de26e4bd23bf523e8a4b7f077df8bfb8e52b50e
+      - uses: reactivecircus/android-emulator-runner@d94c3fbe4fe6a29e4a5ba47c12fb47677c73656b
         env:
           system-image-arch: ${{ matrix.versions.system-image-arch == '' && env.default_system-image-arch || matrix.versions.system-image-arch }}
           system-image-target: ${{ matrix.versions.system-image-target == '' && env.default_system-image-target || matrix.versions.system-image-target }}
@@ -119,7 +119,7 @@ jobs:
           script: echo "Pregenerate the AVD before running Paramedic"
 
       - name: Run paramedic tests
-        uses: reactivecircus/android-emulator-runner@5de26e4bd23bf523e8a4b7f077df8bfb8e52b50e
+        uses: reactivecircus/android-emulator-runner@d94c3fbe4fe6a29e4a5ba47c12fb47677c73656b
         env:
           system-image-arch: ${{ matrix.versions.system-image-arch == '' && env.default_system-image-arch || matrix.versions.system-image-arch }}
           system-image-target: ${{ matrix.versions.system-image-target == '' && env.default_system-image-target || matrix.versions.system-image-target }}

.github/workflows/chrome.yml

@@ -42,8 +42,8 @@ jobs:
       node-version: 16
 
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
           node-version: ${{ env.node-version }}
 
@@ -61,7 +61,7 @@ jobs:
           npm ci
 
       - name: Run paramedic install
-        if: ${{ endswith(env.repo, '/cordova-paramedic')　!= true }}
+        if: ${{ endswith(env.repo, '/cordova-paramedic') != true }}
         run: npm i -g github:apache/cordova-paramedic
 
       - name: Run paramedic tests

.github/workflows/ios.yml

@@ -62,12 +62,16 @@ jobs:
             ios-version: 15.x
             xcode-version: 13.x
 
+          - os-version: macos-12
+            ios-version: 16.x
+            xcode-version: 14.x
+
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
           node-version: ${{ env.node-version }}
-      - uses: maxim-lobanov/setup-xcode@881be567d30efed8fb3f12b5099d68c3fb72aa3d
+      - uses: maxim-lobanov/setup-xcode@9a697e2b393340c3cacd97468baa318e4c883d98
         env:
           xcode-version: ${{ matrix.versions.xcode-version == '' && env.default_xcode-version || matrix.versions.xcode-version }}
         with:

.github/workflows/lint.yml

@@ -37,8 +37,8 @@ jobs:
       node-version: 16
 
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
           node-version: ${{ env.node-version }}
 

README.md

@@ -96,15 +96,15 @@ Each URL is in the form _file:///path/to/spot/_, and can be converted to a
   in here. (_iOS_, _Android_, _BlackBerry 10_, _OSX_, _windows_)
 
 * `cordova.file.externalApplicationStorageDirectory` - Application space on
-  external storage. (_Android_)
+  external storage. (_Android_). See [Quirks](#androids-external-storage-quirks).
 
 * `cordova.file.externalDataDirectory` - Where to put app-specific data files on
-  external storage. (_Android_)
+  external storage. (_Android_). See [Quirks](#androids-external-storage-quirks).
 
 * `cordova.file.externalCacheDirectory` - Application cache on external storage.
-  (_Android_)
+  (_Android_). See [Quirks](#androids-external-storage-quirks).
 
-* `cordova.file.externalRootDirectory` - External storage (SD card) root. (_Android_, _BlackBerry 10_)
+* `cordova.file.externalRootDirectory` - External storage (SD card) root. (_Android_, _BlackBerry 10_). See [Quirks](#androids-external-storage-quirks).
 
 * `cordova.file.tempDirectory` - Temp directory that the OS can clear at will. Do not
   rely on the OS to clear this directory; your app should always remove files as
@@ -179,6 +179,26 @@ the `cordova.file.*` properties map to physical paths on a real device.
 **Note**: If external storage can't be mounted, the `cordova.file.external*`
 properties are `null`.
 
+#### Android's External Storage Quirks
+
+With the introduction of [Scoped Storage](https://source.android.com/docs/core/storage/scoped) access to External Storage is unreliable or limited via File APIs.
+Scoped Storage was introduced in API 29. While existing apps may have the ability to opt out, this option is not available for new apps. On Android API 30 and later, Scoped Storage is fully enforced.
+
+Additionally, Direct File Access **is not** supported on API 29. This means this plugin **cannot** access external storage mediums on API 29 devices.
+
+API 30 introduced [FUSE](https://source.android.com/docs/core/storage/scoped) which allowed limited access to external storage using File APIs, allowing this plugin to
+partially work again.
+
+Limited access includes but isn't limited to:
+- Read only access with appropriate `READ_EXTERNAL` or [READ_MEDIA_*](https://developer.android.com/training/data-storage/shared/media#access-other-apps-files) permissions.
+- Read only access is limited to media files, but not documents.
+- Writes are limited to only files owned by your app. Modifying files owned by a third-party app (including an image file created via the camera plugin for example) is not possible via the File API.
+- Not all paths in external storage is writable.
+
+These limitations only applies to external filesystems (e.g. `cordova.file.external*` paths). Internal filesystems such as `cordova.file.dataDirectory` path are not imposed by these limitations.
+
+If interfacing with the external file system is a requirement for your application, consider using a [MediaStore](https://www.npmjs.com/search?q=ecosystem%3Acordova%20storage%20access%20framework) plugin instead.
+
 ### OS X File System Layout
 
 | Device Path                                      | `cordova.file.*`            | `iosExtraFileSystems` | r/w? |  OS clears | private |

RELEASENOTES.md

@@ -20,6 +20,32 @@
 -->
 # Release Notes
 
+### 8.0.1 (Oct 27, 2023)
+
+**Fixes:**
+
+* [GH-608](https://github.com/apache/cordova-plugin-file/pull/608) fix(android): `hasWritePermission` for SDK 33
+
+**Others:**
+
+* [GH-609](https://github.com/apache/cordova-plugin-file/pull/609) chore: update asf config
+* [GH-607](https://github.com/apache/cordova-plugin-file/pull/607) refactor(android): various cleanup
+* [GH-593](https://github.com/apache/cordova-plugin-file/pull/593) doc(android): expanded on external filesystems limitations
+
+### 8.0.0 (Jul 07, 2023)
+
+* [GH-534](https://github.com/apache/cordova-plugin-file/pull/534) fix(android): `FileError` on a content `resolveLocalFileSystemURL`
+* [GH-566](https://github.com/apache/cordova-plugin-file/pull/566) feat(android): add `READ_MEDIA_*` permissions for Android 13+
+* [GH-576](https://github.com/apache/cordova-plugin-file/pull/576) feat(android)!: bump `cordova-android@12` requirement
+* [GH-575](https://github.com/apache/cordova-plugin-file/pull/575) ci: sync github workflow with paramedic base configs
+* [GH-574](https://github.com/apache/cordova-plugin-file/pull/574) chore: update `@cordova/[email protected]` w/ fixes
+* [GH-556](https://github.com/apache/cordova-plugin-file/pull/556) feat(android)!: remove `WRITE_EXTERNAL_STORAGE` permission from `plugin.xml`
+* [GH-554](https://github.com/apache/cordova-plugin-file/pull/554) spec(android): fix spec based on testing environment
+* [GH-547](https://github.com/apache/cordova-plugin-file/pull/547) fix(types): Mark `FileWriter.write` to support `ArrayBuffer` data
+* [GH-535](https://github.com/apache/cordova-plugin-file/pull/535) ci: sync workflow with paramedic
+* [GH-531](https://github.com/apache/cordova-plugin-file/pull/531) dep(npm): bump package-lock v2 w/ rebuild
+* [GH-529](https://github.com/apache/cordova-plugin-file/pull/529) ci(android): update java requirement for `cordova-android@11`
+
 ### 7.0.0 (Apr 08, 2022)
 
 * [GH-520](https://github.com/apache/cordova-plugin-file/pull/520) test(android): disable `content` scheme tests