# Files and folders

There are three ways to read and write files:

1. **Standard file pickers**: `showOpenFilePicker`, `showSaveFilePicker`, `showDirectoryPicker`, `<input type="file">`. No capability needed; you get whatever the user picks.
2. **`acde:fs`**: files by "root": the app's own private folder, the shared folders it names (Downloads, Documents, ...), and folders the user picked. Suited to apps like file managers and editors. Requires the `fs` capability.
3. **Private storage**: `navigator.storage.getDirectory()` (OPFS), IndexedDB, `localStorage`, for the app's own data.

An app works with handles and root ids, not with absolute paths; only the desktop and its bundled system apps see paths.

## File pickers

They work just like in a browser:

```js
const [handle] = await window.showOpenFilePicker({
  types: [{ description: 'Markdown', accept: { 'text/markdown': ['.md'] } }],
})
const text = await (await handle.getFile()).text()
```

- The dialog is the system's own (the open / save panel on macOS, the file dialog on Windows, the portal on Linux).
- Only this page can read and write the picked file.
- A folder picked with `showDirectoryPicker()` is also **granted to the app**: it shows up as a root in `acde:fs` (`source: 'granted'`) and is still there on the next launch. The default pick is read-only (the root has `mode: 'read_only'`); `showDirectoryPicker({ mode: 'readwrite' })` gives a writable one. Give it back with `fs.revoke(id)`.
- When the user cancels, the promise rejects with `AbortError`. A headless session has no dialog: a picker rejects with `AbortError` there too, unless a test answered it in advance (`chooseFiles`, `chooseFolder`, `chooseSaveFile`; see [Testing](https://docs.dopame.ai/guide/testing.md)).

## acde:fs

```jsonc
{ "capabilities": { "fs": true } }
```

```js
import { fs } from 'acde:fs'

const roots = await fs.roots()
// [{ id: 'private', label: '…', source: 'private', mode: 'writable', reason: null, exists: true }]

await fs.writeFile('private', 'notes/todo.md', '- buy milk\n', { mkdirs: true })

const { entries } = await fs.list('private', 'notes')
const { text, modifiedMs } = await fs.readText('private', 'notes/todo.md')
await fs.writeFile('private', 'notes/todo.md', text + '- a new item\n', { ifModifiedMs: modifiedMs })
```

### Roots

The first argument of every call is a root's **`id`**, and the second is a path under that root. A root's `id` is an opaque name, not a path: `fs.list('/home/me/Downloads')` is rejected.

There are three kinds of root:

| `source` | `id` | What it is | How the app gets it |
| --- | --- | --- | --- |
| `private` | `private` | The app's own data folder, created on first use | `"fs": true` (or any `fs` value) |
| `place` | The place's name, such as `downloads` | A shared folder of the user | Name it in `fs.roots` (see [Shared places](#shared-places)) |
| `granted` | `folder-` plus 16 hex digits | A folder the user picked | `showDirectoryPicker()` |

`roots()` returns one item per root the app can use now: `{id, label, source, mode, reason, exists}`, plus `place` (the place's name) for a shared place. `label` is a name to show the user (the folder's name for a picked folder). `mode` is `writable`, `read_only` (a folder picked without `mode: 'readwrite'`), or `unavailable`; when it is `unavailable`, `reason` says why (`the folder does not exist`) and `exists` is `false`.

Find a picked folder's root by the handle's name:

```js
const handle = await window.showDirectoryPicker({ mode: 'readwrite' })
const picked = (await fs.roots()).find((root) => root.source === 'granted' && root.label === handle.name)
await fs.writeFile(picked.id, 'export.txt', 'hello')
```

**Keep working data in `private`.** It needs no declaration beyond `fs` and no picker, it is always writable, and it is not a root of any other app. Use a shared place or a picked folder only for files the user should find outside the app. On disk the private folder is `$XDG_DATA_HOME/acde/files/<app id>/`, which is handy when debugging; the app itself only knows it as `private`.

### Shared places

```jsonc
{ "capabilities": { "fs": { "roots": ["downloads", "documents"] } } }
```

`fs.roots` lists shared places by name: `desktop`, `documents`, `downloads`, `music`, `pictures`, `videos`. Anything else fails `acdev check`: `fs.roots "work" is not a shared place (desktop, documents, downloads, music, pictures, videos); any other folder is one the user picks (showDirectoryPicker() with "fs": true)`, and for a path, `fs.roots "~/Documents" is not a shared place: write "documents", the runtime finds that folder through the system (also when it was moved)`. `private` and picked folders come with every `fs` value and are not listed.

Declaring a place is what gives the app access to it; the user is not asked. Each named place is then in `roots()` as `{ id: 'downloads', source: 'place', place: 'downloads', … }` and its `id` works as the first argument: `fs.list('downloads')`. When the folder does not exist on this machine, the root has `mode: 'unavailable'` and calls on it reject with `ENOENT`.

### Paths

The second argument is a **relative path** under the root, separated by `/`; `''` (or leaving it out in `list`) is the root itself. Absolute paths, and escaping the root with `..` or a symbolic link, are rejected.

### Common calls

| Call | Returns |
| --- | --- |
| `roots()` | The roots the app can use now |
| `list(root, path?, hidden?)` | `{root, path, entries, truncated, skipped?}`: folders first, at most 5000 entries (`truncated`); hidden entries (a leading dot, on Windows also the hidden or system attribute) only with `hidden` `true`; `skipped` counts entries whose names are not valid Unicode |
| `stat(root, path)` | `{name, kind, size, modifiedMs, version, path}` (does not follow symbolic links) |
| `readText(root, path)` | `{text, modifiedMs, size, version}`, up to 64 MiB, `EILSEQ` if not UTF-8 |
| `readBytes(root, path)` | `{data: Uint8Array, modifiedMs, size, version}`, up to 64 MiB |
| `writeFile(root, path, data, options?)` | Writes text or bytes, up to 64 MiB; returns the entry with its new `version` |
| `readRange(root, path, offset, length, {ifVersion}?)` | `{data, offset, size, modifiedMs, version}`: part of a file, at most 16 MiB at a time; `size` is the whole file's |
| `mkdir(root, path, {recursive?})` | Creates a folder |
| `rename(root, from, to)` | Renames / moves inside one root |
| `delete(root, path)` | Deletes a file or an empty folder: `{status: 'deleted', path}` |
| `copy(fromRoot, fromPath, toRoot, toDir)` | Copies a file or a folder into the folder `toDir` of another root (or the same one); returns the new entry and its `path`. A taken name gets a number (`todo 2.md`) |
| `revoke(id)` | Gives back a folder the user picked |

To bring a file from a shared place or a picked folder into the app's own data, copy it: `await fs.copy('downloads', 'report.txt', 'private', '')`.

### Safe writes

Options for `writeFile`:

- `create`: `'always'` (default, creates the file if missing), `'new'` (`EEXIST` if it already exists), `'never'` (`ENOENT` if it does not exist).
- `ifVersion`: skips the write and fails with `ECONFLICT` if the file is no longer the one you read. Every read returns a `version` (an opaque string that tells two states of the file apart, even two writes in one millisecond); pass it when you write, and you will never overwrite someone else's changes. `ifModifiedMs` does the same with the modification time; `ifVersion` is the safer of the two. Neither goes with `create: 'new'`.
- `mkdirs`: creates the parent folders first. Without it, writing into a folder that does not exist fails with `EINVAL`.

A write replacing a file goes to a temporary file in the same folder first, is fsynced, and then replaces the file atomically (keeping its permissions; on Windows its attributes and ACL), so a crash leaves either the old or the new content. When the folder does not let the app create a file, it writes into the original file instead and the returned entry has `inPlace: true`: that write is not crash-safe.

### Large files

The whole-file calls stop at 64 MiB. For larger files use the standard handles: `getFile()` gives a `File` that reads on demand (`slice()`, `stream()`), and `createWritable()` writes at any position into a temporary file that `close()` puts in place atomically. `acde:fs` has the same as calls: `readRange()` above, and `openWrite(root, path, {keepExistingData, create, ifVersion, mkdirs}?)` → `{id, size}`, then `writeChunk(id, offset, data)` (at most 16 MiB a call), `truncateWrite(id, size)`, and `commitWrite(id)` (returns the entry with its `version`) or `abortWrite(id)`. With `ifVersion`, a change by someone else between the open and the commit is `ECONFLICT` and the file stays as it was. A write that is left alone for 10 minutes is given up.

### Errors

On failure the promise rejects with an `Error` that has a `code` and a `status`:

| `code` | `status` | When |
| --- | --- | --- |
| `EINVAL` | 400 | Invalid arguments, an absolute path or one that escapes the root, a missing parent folder, wrong type, symbolic link |
| `EACCES` | 403 | The first argument is not one of the app's roots, the root is read-only, or the system does not allow it |
| `ENOENT` | 404 | Does not exist |
| `EEXIST` | 409 | Already exists |
| `ECONFLICT` | 409 | Changed or deleted by someone else since it was read (`ifVersion`, `ifModifiedMs`) |
| `ENOTEMPTY` | 409 | Deleting a non-empty folder |
| `EFBIG` | 413 | Exceeds the size limit |
| `EILSEQ` | 400 | `readText` read something that is not UTF-8 |
| `ENOSPC` | 507 | Disk full |
| `EIO` | 500 | Anything else |

```js
try {
  await fs.writeFile(root, path, text, { ifModifiedMs })
} catch (e) {
  if (e.code === 'ECONFLICT') askToReload()
  else throw e
}
```

What the common mistakes look like:

| Mistake | Rejection |
| --- | --- |
| A path as the root: `fs.list('/tmp')` | `EACCES`: `this app may not use the files of /tmp (not one of its roots)` |
| A place that is not in `fs.roots`: `fs.list('downloads')` with `"fs": true` | `EACCES`: `this app may not use the files of downloads (not one of its roots)` |
| An absolute path as the second argument: `fs.readText('private', '/etc/hosts')` | `EINVAL`: `path must be relative to the workspace` |
| `..` out of the root: `fs.readText('private', '../x')` | `EINVAL`: `path escapes the workspace` |
| Writing into a folder that does not exist, without `mkdirs` | `EINVAL`: `parent directory is missing or outside the workspace` |
| Writing to a folder picked without `mode: 'readwrite'` | `EACCES`: `<folder> was picked read-only` |
| `fs.locate(path)` or `fs.openPath(root, path)` (they turn paths into roots and back) | `EACCES`: `fs.locate() works only in system apps that declare shared places` |

## Dropped files

When files or folders are dragged from the host system into a window, the page receives the standard drag events, ending in `drop`, and `dataTransfer` carries the files the standard way. The page gets no path.

- Each dropped file or folder is an item of `dataTransfer.items` with `kind: 'file'`; `item.getAsFileSystemHandle()` resolves to a **read-only** `FileSystemFileHandle` or `FileSystemDirectoryHandle` (`createWritable()` rejects with `NotAllowedError`).
- Files up to 64 MiB are also in `dataTransfer.files`. Folders and larger files are not; use their handles.
- `dataTransfer.types` is `['Files']`; there is no `text/uri-list` or `text/plain` with the paths.

To keep a dropped file, copy its content into `private`:

```js
import { fs } from 'acde:fs'

addEventListener('dragover', (event) => event.preventDefault())
addEventListener('drop', async (event) => {
  event.preventDefault()
  const items = [...event.dataTransfer.items].filter((item) => item.kind === 'file')
  const handles = await Promise.all(items.map((item) => item.getAsFileSystemHandle()))
  for (const handle of handles) {
    if (handle.kind !== 'file') continue
    const file = await handle.getFile()
    await fs.writeFile('private', `inbox/${file.name}`, new Uint8Array(await file.arrayBuffer()), { mkdirs: true })
  }
})
```

A handle (from a drop, a picker, or an open request) can also be handed to another app; see [Opening apps](https://docs.dopame.ai/guide/open.md#files-and-links).
