File System

Docs: https://docs.api.kunkun.sh/interfaces/ui.IFs

The File System API can be used to read/write files and directories, and search for files.

File System access requires scoped permissions.

Only the directories specified in the permissions can be accessed.

APIs and Required Permissions

• readDir: [ fs:readfs:read-dir ]
• readFile: [ fs:read ]
• readTextFile: [ fs:read ]
• stat: [ fs:statfs:read ]
• lstat: [ fs:statfs:read ]
• exists: [ fs:existsfs:read ]
• mkdir: [ fs:write ]
• create: [ fs:write ]
• copyFile: [ fs:write ]
• remove: [ fs:write ]
• rename: [ fs:write ]
• truncate: [ fs:write ]
• writeFile: [ fs:write ]
• writeTextFile: [ fs:write ]
• fileSearch: [ fs:search ]

The APIs are very intuitive by their names, so I won’t explain every API here. See the auto-generated API documentation for more details and their type definitions.

I will explain how the scoped permission works and the file search API in the following sections.

Scoped Permission

To access a file, or directory, or directory recursively, you need to specify the path pattern in the permission.

Since KK is cross-platform, the path is different on different platforms.

You need to use path alias to specify the path.

Path Alias

• $DESKTOP
• $DOCUMENT
• $DOWNLOAD
• $HOME
• $APPDATA
• $EXTENSION

Currently, only these aliases are supported. Files outside these directories are inaccessible.

For example, this is an example permission to access the projects.json file of VSCode Project Manager extension config file on all 3 platforms.

You may need "os:all" permission to get current platform to know which path to read in the extension code.

package.json

...
"permissions": [
  "os:all",
  {
    "permission": "fs:read",
    "allow": [
      {
        "path": "$HOME/Library/Application Support/Code/User/globalStorage/alefragnani.project-manager/projects.json"
      },
      {
        "path": "$HOME/.config/Code/User/globalStorage/alefragnani.project-manager/projects.json"
      },
      {
        "path": "$APPDATA/Code/User/globalStorage/alefragnani.project-manager/projects.json"
      }
    ]
  }
],
...

Here is how to use the API in JS. A baseDir parameter can be provided as well.

import { fs, path } from "@kksh/api/ui/worker"
// or
import { fs, path } from "@kksh/api/ui/iframe"

const fileContent: string = await fs.readTextFile(
    "Library/Application Support/Code/User/globalStorage/alefragnani.project-manager/projects.json",
    { baseDir: path.BaseDirectory.Home }
  )

Directory Access

To list items in a directory

package.json

...
"permissions": [
  "os:all",
  {
    "permission": "fs:read-dir",
    "allow": [
      {
        "path": "$DOWNLOAD"
      }
    ]
  },
],
...

const downloads: string[] = await fs.readDir("Downloads", { baseDir: path.BaseDirectory.Home })
// or
const downloads: string[] = await fs.readDir(await path.downloadDir())

Suppose we have this file tree structure, and we want to list items in kunkun folder.

• DirectoryHome

  • DirectoryDownloads

    • Directorykunkun

      • file.txt
      • file2.txt

This is how to access the kunkun folder from js, but will got permission denied with the previous permission (i.e. "$DOWNLOAD").

const downloads = await fs.readDir("Downloads/kunkun",
  {
    baseDir: path.BaseDirectory.Home
  }
)

The path scope permission should be changed to "$DOWNLOAD/*" to access everything under the Downloads directory.

package.json

...
"permissions": [
  "os:all",
  {
    "permission": "fs:read-dir",
    "allow": [
      {
        "path": "$DOWNLOAD/*"
      }
    ]
  },
],
...

Recursive Directory Access

To access file.txt in the kunkun folder, the path scope should be changed to "$DOWNLOAD/kunkun/file.txt" if you only want to access this file.,

Or "$DOWNLOAD/**" if you want to access everything under the Downloads directory.

File Search API

The file search API is used to search for files in a directory.

Here is an example of searching for a file named file.txt in the Downloads directory.

const searchRes: string[] = await fs.fileSearch({
  locations: [await path.downloadDir()],
  query: "file.txt",
})

Each search location must be specified in the permission under fs:search permission.

package.json

...
"permissions": [
  {
    "permission": "fs:search",
    "allow": [
      {
        "path": "$DOWNLOAD"
      }
    ]
  },
],
...

More search options are provided, check the API documentation for more details.

• locations
• query
• ext
• depth
• limit
• hidden
• ignore_case
• file_size_greater
• file_size_smaller
• file_size_equal
• created_after
• created_before
• modified_after
• modified_before