Filesystem
The Filesystem Aptitude provides the ability to interact with files on the system (including things reading, writing, and deleting).
Each Loop is provided with their own blank "working" directory for this Aptitude, which is what relative paths resolve to. Loops are free to do anything they want to any file/directory inside of this working directory.
Loops cannot access other Loops' working directories.
This working directory persists across Loop version updates.
API
Example
Permissions

copy

Copies a file from one location to another.
1
import { filesystem } from '@oliveai/ldk';
2
3
const SOURCE_PATH = '/var/log/system.log';
4
const DESTINATION_PATH = '/Users/username/system.log';
5
6
// Check to make sure the system log exists
7
const systemLogExists = await filesystem.exists(SOURCE_PATH);
8
9
// Copy the system log to the user folder
10
if (systemLogExists) {
11
await filesystem.copy(SOURCE_PATH, DESTINATION_PATH);
12
}
Copied!

dir

Returns all files in the specified directory.
1
import { filesystem } from '@oliveai/ldk';
2
3
// Get all files in the /var/log directory
4
const allLogs = await filesystem.dir('/var/log');
5
6
/*
7
allLogs:
8
[
9
{
10
"name": "foo.txt",
11
"size": 476,
12
"mode": "-rw-r--r--",
13
"modTime": "2021-10-18T12:46:16.234535644-04:00",
14
"isDir": false
15
},
16
{
17
"name": "bar",
18
"size": 96,
19
"mode": "drwxr-xr-x",
20
"modTime": "2021-09-19T05:25:54.491321266-04:00",
21
"isDir": true
22
},
23
...
24
]
25
*/
Copied!

exists

Return true if a file or directory exists at the specified location.
1
import { filesystem } from '@oliveai/ldk';
2
3
// Check to make sure /var/log directory exists
4
const logDirExists = await filesystem.exists('/var/log');
5
// logDirExists === true
6
7
// Check to make sure /var/log/system.log file exists
8
const sysLogExists = await filesystem.exists('/var/log/system.log');
9
// sysLogExists === true
10
11
// Check to make sure /var/log/fakeDirectory directory exists
12
const fakeDirExists = await filesystem.exists('/var/log/fakeDirectory');
13
// fakeDirExists === false
Copied!

join

Join joins an array of path elements into a single path, separating them with an OS specific Separator. Empty elements are ignored. The result is cleaned. However, if the argument list is empty or all its elements are empty, Join returns an empty string. On Windows, the result will only be a UNC path if the first non-empty element is a UNC path.
1
import { filesystem } from '@oliveai/ldk';
2
3
// Create path string for a local text file that works on both
4
// Windows and Unix-based systems
5
const testDirectory = await filesystem.join(['testDirectory', 'foo.txt']);
6
// Windows: testDirectory == testDirectory\foo.txt
7
// macOS: testDirectory == testDirectory/foo.txt
Copied!

listenDir

Listen for changes to the contents of the directory.
1
import { filesystem } from '@oliveai/ldk';
2
3
// The path of the directory where we want to listen for changes
4
const PATH = '/var/log';
5
// The callback function that runs when a change is detected
6
const callback = (fileEvent) => {
7
// When a file or directory are added, opened, or updated:
8
/*
9
fileEvent:
10
{
11
"info": {
12
"name": "foo.log",
13
"size": 17,
14
"mode": "-rwxr-xr-x",
15
"modTime": "2021-10-27T22:14:24.596962-04:00",
16
"isDir": false
17
},
18
"action": "Create" or "Chmod"
19
}
20
*/
21
22
// When a file or directory is renamed or removed, it will fire off
23
// the above fileEvent then another one afterward:
24
/*
25
fileEvent:
26
{
27
"action": "Rename" or "Remove",
28
"name": "test.log" // old file name
29
}
30
*/
31
}
32
33
const directoryListener = await filesystem.listenDir(PATH, callback);
34
35
// Cancel the listener
36
directoryListen.cancel();
Copied!

listenFile

Listen for changes to a specific file.
1
import { filesystem } from '@oliveai/ldk';
2
3
// The path of the file we want to listen to for changes
4
const PATH = '/var/log/system.log';
5
// The callback function that runs when a change is detected
6
const callback = (fileEvent) => {
7
// When the file is opened or updated:
8
/*
9
fileEvent:
10
{
11
"info": {
12
"name": "system.log",
13
"size": 14592,
14
"mode": "-rwxr-xr-x",
15
"modTime": "2021-10-27T22:31:24.215811-04:00",
16
"isDir": false
17
},
18
"action": "Chmod"
19
}
20
*/
21
22
// When the file is renamed or removed, it will fire off
23
// the above fileEvent then another one afterward:
24
/*
25
fileEvent:
26
{
27
"action": "Rename" or "Remove",
28
"name": "system.log" // old file name
29
}
30
*/
31
}
32
33
const fileListener = await filesystem.listenFile(PATH, callback);
34
35
// Cancel the listener
36
fileListener.cancel();
Copied!

makeDir

Makes a directory at the specified location.
1
import { filesystem } from '@oliveai/ldk';
2
3
// The path of the directory we want to create
4
const DESTINATION_PATH = '/var/log/backups';
5
6
// The permissions we want to give the directory, in octal format
7
// https://www.linode.com/docs/guides/modify-file-permissions-with-chmod/
8
const WRITE_MODE = 0o750
9
10
// Check to make sure the directory doesn't already exist
11
const directoryExists = await filesystem.exists(DESTINATION_PATH);
12
13
if (!directoryExists) {
14
await filesystem.makeDir(DESTINATION_PATH, WRITE_MODE);
15
}
Copied!

move

Moves a file from one location to another.
1
import { filesystem } from '@oliveai/ldk';
2
3
const SOURCE_PATH = '/var/log/system.log';
4
const DESTINATION_PATH = '/Users/username/system.log';
5
6
// Check to make sure the system log exists
7
const systemLogExists = await filesystem.exists(SOURCE_PATH);
8
9
// Move the system log to the user folder
10
await filesystem.move(SOURCE_PATH, DESTINATION_PATH);
Copied!

openWithDefaultApplication

Opens a file using the default tool for the extension provided in the path parameter, including directories. Limited to .csv, .doc, .docx, .pdf, .txt, .xls, .xlsx
1
import { filesystem } from '@oliveai/ldk';
2
3
// Open foo.txt in the loop directory
4
await filesystem.openWithDefaultApplication('foo.txt')
Copied!

readFile

Returns the contents of the specified file.
1
import { filesystem, network } from '@oliveai/ldk';
2
3
// Path of the system log that we want to read
4
const FILE_PATH = '/var/log/system.log';
5
6
// Get the contents of the system log, returned as a Uint8Array
7
const encodedSysLog = await filesystem.readFile(FILE_PATH);
8
9
// Decode the contents to get the actual string value
10
const decodedSysLog = await network.decode(encodedSysLog);
11
12
// decodedSysLog === human readable string of system.log contents
Copied!

remove

Removes a file/directory at the specified path.
1
import { filesystem } from '@oliveai/ldk';
2
3
// Path of foo.txt in the local loop directory
4
const FILE_PATH = 'foo.txt';
5
6
// Delete foo.txt
7
await filesystem.remove(FILE_PATH);
Copied!

stat

Returns info about a specified file/directory.
1
import { filesystem } from '@oliveai/ldk';
2
3
const DIRECTORY_PATH = '/var/log';
4
const FILE_PATH = '/var/log/system.log';
5
6
const directoryInfo = await filesystem.stat(DIRECTORY_PATH);
7
/*
8
directoryInfo:
9
{
10
"name": "log",
11
"size": 1408,
12
"mode": "drwxr-xr-x",
13
"modTime": "2021-10-28T01:01:11.003025289-04:00",
14
"isDir": true
15
}
16
*/
17
18
const fileInfo = await filesystem.stat(FILE_PATH);
19
/*
20
system.log:
21
{
22
"name": "system.log",
23
"size": 353232,
24
"mode": "-rw-r-----",
25
"modTime": "2021-10-28T12:29:25.305970009-04:00",
26
"isDir": false
27
}
28
*/
Copied!

unzip

Unzips sourced file to a specified directory.
1
import { filesystem } from '@oliveai/ldk';
2
3
// foo.zip is in the local loop directory, and contains bar.txt
4
// Unzip the contents of foo.zip to the directory "baz"
5
await filesystem.unzip('foo.zip', 'baz');
6
7
const unzipSuccessful = await filesystem.exists('baz/bar.txt');
8
// unzipSuccessful === true
Copied!

workDir

Get the Loop's working directory
1
import { filesystem } from '@oliveai/ldk';
2
3
// Get the full path to the loop's working directory
4
const loopPath = await filesystem.workDir();
5
6
// macOS: loopPath === /Users/username/Library/Application Support/Olive Helps/secureloopWork/123456-unique-loop-id
7
// Windows: loopPath === C:\Users\username\AppData\Roaming\Olive Helps\secureloopWork\123456-unique-loop-id
Copied!

writeFile

1
import { filesystem } from '@oliveai/ldk';
2
3
// The content we'll be putting in the file
4
const FILE_CONTENT = 'Some test text to put in a file';
5
6
// The path in the loop directory for the file
7
const DIRECTORY = 'foo';
8
const FILE_NAME = 'bar.txt';
9
const filePath = await filesystem.join([DIRECTORY, FILE_NAME]);
10
11
// The permissions we want to give the file, in octal format
12
// https://www.linode.com/docs/guides/modify-file-permissions-with-chmod/
13
const FILE_PERMISSIONS = 0o750;
14
15
// The write operations to choose from while writing the file
16
const { overwrite, append } = filesystem.WriteOperation;
17
18
const writeFileParams = {
19
data: FILE_CONTENT,
20
path: filePath,
21
writeMode: FILE_PERMISSIONS,
22
writeOperation: overwrite
23
};
24
25
await filesystem.writeFile(writeFileParams);
Copied!
In this example, we use the Clipboard aptitude to listen for you copying text to the clipboard, and automatically append it to a file in the local Loop directory. This could be useful to pair with a button/toggle in a Whisper, where this capability can be enabled before rapidly copying several items, pasted into the file, then toggle it off when finished.
1
import { filesystem, clipboard } from '@oliveai/ldk';
2
3
const FILE_NAME = 'clipboardPastes.txt';
4
const baseWriteFileParams = {
5
data: '',
6
path: FILE_NAME,
7
writeMode: 0o755,
8
writeOperation: filesystem.WriteOperation.append,
9
};
10
11
// Include clipboard events that happen while the
12
// Olive Helps window is in focus
13
const INCLUDE_OLIVE_HELPS_EVENTS = true;
14
15
clipboard.listen(INCLUDE_OLIVE_HELPS_EVENTS, (clipboardText) => {
16
const writeFileParams = {
17
...baseWriteFileParams,
18
data: clipboardText + '\n',
19
};
20
21
await filesystem.writeFile(writeFileParams);
22
});
Copied!
Listen to directory for zip files and automatically unzip then delete zip file. This could be customized with the Dropzone component to select the exact folder to monitor for ZIP files.
1
import { filesystem } from '@oliveai/ldk';
2
3
// Here we're declaring the downloads folder, but this can be chosen by the
4
// user using the Dropzone component in a Whisper
5
const downloadsFolder = '/Users/username/Downloads';
6
7
filesystem.listenDir(downloadsFolder, async (fileEvent) => {
8
const { action, info } = fileEvent;
9
10
// If a file was "created" in this directory
11
if (action === 'Create' && info) {
12
const { name: fileName } = info;
13
14
// If the file is a zip file, unzip it
15
if (fileName.endsWith('.zip')) {
16
const zipFilePath = await filesystem.join([downloadsFolder, fileName]);
17
18
// Unzip the contents to the Downloads folder
19
await filesystem.unzip(zipFilePath, downloadsFolder);
20
21
// Delete the zip file after unzipping
22
await filesystem.remove(zipFilePath);
23
}
24
}
25
});
Copied!
To use the Filesystem aptitude, use the following permissions outline in your package.json under the ldk object.
1
...
2
"ldk": {
3
"permissions": {
4
"filesystem": {
5
"pathGlobs": [
6
{
7
"value": "string"
8
},
9
...
10
]
11
},
12
...
13
}
14
},
15
...
Copied!
Each value can either refer to an exact absolute path or use a glob wildcard. The only supported wildcards are ** and *, and can be used anywhere in the path.
Relative file paths can be accessed without specifying them in the permissions list.

Examples

1
{
2
"ldk": {
3
"permissions": {
4
"filesystem": {
5
"pathGlobs": [
6
{
7
// Provides access to all files in the /tmp directory that have a .txt extension.
8
"value": "/tmp/*.txt"
9
},
10
{
11
// Provides access to all directories and files under the /tmp directory.
12
"value": "/tmp/**"
13
},
14
{
15
// Provides access to all files with .txt extensions in the /tmp directory or any of its subdirectories.
16
"value": "/tmp/**/*.txt"
17
},
18
{
19
// Provides access to all files with .txt extensions in any subdirectory of /tmp.
20
"value": "/tmp/*/*.txt"
21
}
22
]
23
}
24
}
25
}
26
}
Copied!
Last modified 5d ago
Copy link