# `memory-fs`

## Purpose

In-memory implementation of `MutableInstallerFs`. Used by the testing
harness (`runPlugin` constructs one if the caller doesn't supply one) and
by anything that needs deterministic, side-effect-free filesystem
behaviour: integration tests, dry-run inspection of large plugins,
fixture seeding for replays. POSIX-style paths only; Windows-style
backslashes are normalised to forward slashes on entry.

## Features

- Seedable from a `Record<string, string | Uint8Array>` map at
  construction time — strings are UTF-8 encoded automatically.
- Tracks directories as first-class entries, so `listDir` returns
  deterministic, sorted results without sniffing files for shared
  prefixes.
- `writeFile`/`mkdir` create intermediate directories implicitly.
- `deleteFile` refuses to remove a non-empty directory (`ENOTEMPTY`); empty
  dirs delete cleanly.
- `snapshot()` returns a `{ path: Uint8Array }` map of every file — handy
  for end-of-test assertions.
- Honours an optional `AbortSignal` — every async call short-circuits
  with an `AbortError` once the signal aborts.

## Basic Example

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

const fs = new MemoryFs({ seed: { "/README.md": "# hi\n" } });
const bytes = await fs.readFile("/README.md");
console.log(new TextDecoder().decode(bytes));
```

## Advanced Example

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

const ac = new AbortController();
const fs = new MemoryFs({ signal: ac.signal });

await fs.mkdir("/.suaveplan/skills");
await fs.writeJson("/.suaveplan/skills/index.json", { skills: [] });
await fs.writeFile(
    "/.suaveplan/skills/echo/SKILL.md",
    new TextEncoder().encode("# echo\n")
);

const list = await fs.listDir("/.suaveplan/skills");
console.log(list); // ["echo", "index.json"]

ac.abort();
await fs.writeFile("/late.txt", new Uint8Array()); // throws AbortError
```

## API Reference

- `new MemoryFs(options?: { seed?, signal? })`
- `pathOf(...segments): string`
- `exists(path): Promise<boolean>`
- `stat(path): Promise<{ size, isFile, isDir }>`
- `readFile(path): Promise<Uint8Array>`
- `readJson<T>(path): Promise<T>`
- `listDir(path): Promise<string[]>`
- `writeFile(path, contents, mode?): Promise<void>`
- `deleteFile(path): Promise<void>`
- `mkdir(path): Promise<void>`
- `rename(from, to): Promise<void>`
- `writeJson(path, value): Promise<void>`
- `snapshot(): Record<string, Uint8Array>`

## Implementation Notes

Path normalisation collapses repeated slashes, strips trailing slashes
(except at the root), and canonicalises backslashes. Seeding paths whose
parents collide with an already-seeded *file* throws `ENOTDIR` — this is
intentional and mirrors POSIX behaviour. The internal `entries` map is
ordered by insertion; `listDir` re-sorts on every call so results are
stable regardless of write order.