Extension

Defined in: packages/core/src/kernel/types.ts:1846

The atomic unit of composition. Everything — presets, packages, .use() args — is an Extension.

Role

Author one (or return one from a preset factory) to register bins, mounts, env vars, files, services, or man pages into a system image.

Remarks

Pure data: no behavior, no callbacks, no lifecycle hooks. A preset is a plain function that returns an Extension; .use(ext) accumulates them in order. Merge semantics (via mergeExtensions): bins/env/mounts/ files/man are last-wins per key with a console.warn on override; services are concatenated and dedup-by-name with last-wins.

Caveat

Extensions are merged at .build() time, not .use() time — the builder is immutable and accumulates Extension arrays. Conflict warnings surface during build(), not earlier.

Example

import { Unix, stdSystem, exitCode, type Extension } from '@fishnet/core'
const myExt: Extension = {
  bins: { hello: async (p) => { await p.stdout.write('hi\n'); return exitCode(0) } },
  env: { GREETING: 'hi' },
}
const image = await Unix().use(stdSystem()).use(myExt).build()

See

• mergeExtensions
• UnixBuilder
• ServiceDef

Properties

bins?

optional bins?: Record<string, BinFunction>

Defined in: packages/core/src/kernel/types.ts:1850

Bin functions registered at /bin/<name>. Later wins per name.

---

env?

optional env?: Record<string, string>

Defined in: packages/core/src/kernel/types.ts:1852

Environment variables. Later wins per key.

---

files?

optional files?: Record<string, string>

Defined in: packages/core/src/kernel/types.ts:1854

Seed files written after mounts are established. Later wins per path.

---

man?

optional man?: Record<string, BinHelp>

Defined in: packages/core/src/kernel/types.ts:1858

Man page content for bins. Key is bin name. Later wins per name.

---

mounts?

optional mounts?: Record<string, Fileserver>

Defined in: packages/core/src/kernel/types.ts:1848

Fileserver mounts. Key is the mount path (e.g., '/data'). Later wins per path.

---

services?

optional services?: ServiceDef[]

Defined in: packages/core/src/kernel/types.ts:1856

Service declarations for the init system. Collected in order across extensions.