# `installer-fs`

## Purpose

Re-exports the read-only `InstallerFs` interface from the types module and
declares its mutating extension `MutableInstallerFs`. Plugins receive a
read-only `InstallerFs` through the context — they can describe writes via
`FileOp[]` but cannot perform them directly. The host uses
`MutableInstallerFs` internally to materialise ops with rollback. Keeping
the read/write split at the interface level is what makes `--dry-run`
trivially correct: a dry-run never resolves the mutating subset.

## Features

- Single source of truth for filesystem capability boundaries inside the
  installer.
- `MutableInstallerFs` extends `InstallerFs` with `writeFile`, `deleteFile`,
  `mkdir`, `rename`, and `writeJson`.
- Both `MemoryFs` and `DiskFs` implement `MutableInstallerFs`, but only the
  read-only view is ever handed to plugin code.

## Basic Example

```ts
import { MemoryFs, type InstallerFs } from "@suaveplan/installer";

async function describe(fs: InstallerFs): Promise<number> {
    const entries = await fs.listDir("/");
    return entries.length;
}

const fs = new MemoryFs({ seed: { "/a.txt": "hi" } });
await describe(fs);
```

## Advanced Example

```ts
import {
    type MutableInstallerFs,
    MemoryFs,
} from "@suaveplan/installer";

async function backupThenWrite(
    fs: MutableInstallerFs,
    path: string,
    next: Uint8Array
): Promise<void> {
    if (await fs.exists(path)) {
        const prior = await fs.readFile(path);
        await fs.writeFile(`${path}.bak`, prior);
    }
    await fs.writeFile(path, next);
}

await backupThenWrite(new MemoryFs(), "/cfg.json", new Uint8Array([123, 125]));
```

## API Reference

- `interface InstallerFs` (re-export from `types/installer.types.ts`):
  `exists`, `readFile`, `readJson`, `stat`, `listDir`, `pathOf`.
- `interface MutableInstallerFs extends InstallerFs`:
  `writeFile(path, contents, mode?)`, `deleteFile(path)`, `mkdir(path)`,
  `rename(from, to)`, `writeJson(path, value)`.

## Implementation Notes

`MutableInstallerFs` is exposed publicly through `./fs` so authors who want
to write a custom backing store (e.g. an S3-backed installer fs) have a
single contract to satisfy. Implementations must honour any `AbortSignal`
they were constructed with — both in-tree implementations call a shared
`ensureNotAborted(signal)` helper at the start of every async operation.
The interface deliberately has no `chmod` or `chown` operations: per-file
mode is carried on the `WriteOp` itself, and ownership is left to the
host filesystem.