@mounaji_npm/agentfs 0.2.0

package/README.md

@@ -0,0 +1,70 @@
+# @mounaji_npm/agentfs
+
+A per-agent, portable filesystem home for AI agents. Each agent gets a
+`yoagent-<id>/` directory under a configurable root, with a fixed set of
+**layers** plus room for custom nested folders, a `manifest.json`, and
+dependency-free `.tar.gz` **export/import bundles** — the foundation for
+portable Tier S agents.
+
+Zero runtime dependencies (Node built-ins only).
+
+## Layers
+
+`learning · skills · memory · preferences · rules · soul · user · assets`
+
+## Usage
+
+```js
+import { createAgentFs, AgentFs } from '@mounaji_npm/agentfs';
+
+// Create + ensure the layered home exists.
+const fs = createAgentFs({ root: '/data/agents', agentId: 'abc123' });
+
+fs.writeJson('memory/facts.json', { likes: ['dark mode'] });
+fs.appendFile('learning/feedback_log.jsonl', JSON.stringify({ ok: true }) + '\n');
+fs.writeFile('assets/logo.png', someBuffer);
+fs.patchManifest({ custom: { tier: 'S' } });
+
+fs.listFiles('memory');          // ['memory/facts.json']
+fs.readJson('memory/facts.json');// { likes: ['dark mode'] }
+
+// Portable export → import (round-trips every file, text or binary).
+const bundle = fs.exportBundle();                 // Buffer (.tar.gz)
+const clone  = AgentFs.fromBundle(bundle, { root: '/tmp', agentId: 'abc123' });
+```
+
+## API
+
+### `createAgentFs({ root?, agentId, layers? })` → `AgentFs`
+Constructs and `ensure()`s the agent home. `root` defaults to
+`~/.yoagent/agents`; the agent lives at `<root>/yoagent-<agentId>`.
+
+### `AgentFs`
+- `ensure()` — create the agent dir, all layers, and manifest (idempotent).
+- `path(...segments)` / `layerPath(layer)` — absolute paths (traversal-guarded).
+- `writeFile / readFile / appendFile / writeJson / readJson / exists / mkdir / remove`
+  — file ops on **agent-relative** paths (`memory/facts.json`).
+- `listFiles(relDir?)` — recursive, sorted, forward-slashed relative paths.
+- `readManifest / writeManifest / patchManifest`.
+- `exportBundle()` → `Buffer` — gzipped tar of the whole agent tree.
+- `importBundle(bundle, { overwrite=true })` → `{ written, total }`.
+- `AgentFs.fromBundle(bundle, { root, agentId?, overwrite? })` — rehydrate an
+  agent (infers `agentId` from the bundle manifest if omitted).
+
+### Archive helpers
+`packTar · unpackTar · packTarGz · unpackTarGz` — a minimal, standard-compatible
+tar (ustar) implementation for regular files. Produced archives open with
+`tar -xzf`.
+
+## Notes
+
+- Paths are guarded: any attempt to escape the agent directory (`../…`) throws.
+- Bundles are standard `.tar.gz`; inspect with `tar -tzf agent.tar.gz`.
+- The `learning/` layer is designed to hold
+  [`@mounaji_npm/learning-core`](../learning-core) state.
+
+## Test
+
+```bash
+npm test   # node --test
+```

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mounaji_npm/agentfs",
+  "version": "0.2.0",
+  "description": "Per-agent filesystem — a portable, layered home directory for an AI agent (learning, skills, memory, preferences, rules, soul, user, assets) with a manifest and dependency-free tar.gz export/import bundles. Foundation for portable Tier S agents.",
+  "keywords": [
+    "agent",
+    "filesystem",
+    "agentfs",
+    "portable",
+    "export",
+    "bundle",
+    "learning",
+    "mounaji"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "echo 'agentfs is source-only, no build needed'",
+    "test": "node --test"
+  }
+}

package/src/agentfs.js

@@ -0,0 +1,253 @@
+/**
+ * AgentFs — a per-agent filesystem home.
+ *
+ * Each agent gets a directory `yoagent-<id>/` under a configurable root, with a
+ * fixed set of "layers" (subdirectories) plus room for custom nested folders,
+ * and a `manifest.json` describing it. The whole tree round-trips through a
+ * dependency-free `.tar.gz` bundle (`exportBundle`/`importBundle`), which is the
+ * foundation for portable Tier S agents.
+ *
+ * Layers (from the platform's YOAgent design):
+ *   learning/     — neural weighting engine data (see @mounaji_npm/learning-core)
+ *   skills/       — SKILL.md definitions
+ *   memory/       — persistent memory (facts, decisions, ...)
+ *   preferences/  — user/coding preferences
+ *   rules/        — execution rules
+ *   soul/         — identity/persona
+ *   user/         — user-scoped data
+ *   assets/       — binary assets
+ */
+import { join, resolve, dirname, sep, relative, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import {
+  mkdirSync, existsSync, readFileSync, writeFileSync, appendFileSync,
+  rmSync, readdirSync, statSync,
+} from 'node:fs';
+import { packTarGz, unpackTarGz } from './tar.js';
+
+/** Canonical layer names created for every agent. */
+export const DEFAULT_LAYERS = Object.freeze([
+  'learning', 'skills', 'memory', 'preferences', 'rules', 'soul', 'user', 'assets',
+]);
+
+const MANIFEST_FILE = 'manifest.json';
+const MANIFEST_VERSION = 1;
+
+/** Expand a leading `~/` and resolve to an absolute path. */
+function expandRoot(root) {
+  if (!root) return join(homedir(), '.yoagent', 'agents');
+  if (root.startsWith('~/')) return join(homedir(), root.slice(2));
+  return resolve(root);
+}
+
+/** Normalize an agent-relative path and guard against escaping the agent dir. */
+function safeRelative(relPath) {
+  const normalized = relPath.replace(/\\/g, '/').replace(/^\/+/, '');
+  const joined = join('/agent-root', normalized);
+  const rel = relative('/agent-root', joined);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`agentfs: path escapes agent directory: "${relPath}"`);
+  }
+  return normalized;
+}
+
+export class AgentFs {
+  /**
+   * @param {{ root?: string, agentId: string, layers?: string[] }} opts
+   *   root    — parent directory holding all agents (default ~/.yoagent/agents)
+   *   agentId — stable id; the agent lives at `<root>/yoagent-<agentId>`
+   *   layers  — override the default layer set (custom layers still allowed at runtime)
+   */
+  constructor({ root, agentId, layers } = {}) {
+    if (!agentId || typeof agentId !== 'string') {
+      throw new Error('agentfs: agentId is required');
+    }
+    this.agentId = agentId;
+    this.rootDir = expandRoot(root);
+    this.dir = join(this.rootDir, `yoagent-${agentId}`);
+    this.layers = layers && layers.length ? [...layers] : [...DEFAULT_LAYERS];
+  }
+
+  /** Absolute path to an agent-relative location. */
+  path(...segments) {
+    const rel = safeRelative(segments.join('/'));
+    return join(this.dir, rel);
+  }
+
+  /** Absolute path to a layer directory. */
+  layerPath(layer) {
+    if (!layer) throw new Error('agentfs: layer name required');
+    return this.path(safeRelative(layer));
+  }
+
+  /** Create the agent directory, all layers, and the manifest. Idempotent. */
+  ensure() {
+    mkdirSync(this.dir, { recursive: true });
+    for (const layer of this.layers) {
+      mkdirSync(this.path(layer), { recursive: true });
+    }
+    if (!existsSync(this.path(MANIFEST_FILE))) {
+      const now = new Date().toISOString();
+      this.writeManifest({
+        agentId: this.agentId,
+        version: MANIFEST_VERSION,
+        createdAt: now,
+        updatedAt: now,
+        layers: this.layers,
+        custom: {},
+      });
+    }
+    return this;
+  }
+
+  // ── Manifest ───────────────────────────────────────────────────────────────
+
+  readManifest() {
+    try {
+      return JSON.parse(readFileSync(this.path(MANIFEST_FILE), 'utf-8'));
+    } catch {
+      return null;
+    }
+  }
+
+  writeManifest(manifest) {
+    mkdirSync(this.dir, { recursive: true });
+    writeFileSync(this.path(MANIFEST_FILE), JSON.stringify(manifest, null, 2));
+    return manifest;
+  }
+
+  /** Shallow-merge `patch` into the manifest and bump `updatedAt`. */
+  patchManifest(patch) {
+    const current = this.readManifest() || { agentId: this.agentId, version: MANIFEST_VERSION, custom: {} };
+    const next = { ...current, ...patch, updatedAt: new Date().toISOString() };
+    return this.writeManifest(next);
+  }
+
+  // ── File operations (agent-relative paths) ──────────────────────────────────
+
+  exists(relPath) {
+    return existsSync(this.path(relPath));
+  }
+
+  writeFile(relPath, content) {
+    const abs = this.path(relPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    return abs;
+  }
+
+  readFile(relPath, encoding = 'utf-8') {
+    return readFileSync(this.path(relPath), encoding);
+  }
+
+  appendFile(relPath, content) {
+    const abs = this.path(relPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    appendFileSync(abs, content);
+    return abs;
+  }
+
+  writeJson(relPath, data) {
+    return this.writeFile(relPath, JSON.stringify(data, null, 2));
+  }
+
+  readJson(relPath, fallback = null) {
+    try {
+      return JSON.parse(this.readFile(relPath));
+    } catch {
+      return fallback;
+    }
+  }
+
+  /** Create a directory (agent-relative). Recursive, idempotent. */
+  mkdir(relDir) {
+    const abs = this.path(relDir);
+    mkdirSync(abs, { recursive: true });
+    return abs;
+  }
+
+  remove(relPath) {
+    rmSync(this.path(relPath), { recursive: true, force: true });
+  }
+
+  /**
+   * List regular files under the agent dir (or a sub-path), agent-relative,
+   * using forward slashes. Recurses into subdirectories.
+   */
+  listFiles(relDir = '.') {
+    const base = this.path(relDir);
+    const out = [];
+    const walk = (absDir) => {
+      let entries;
+      try {
+        entries = readdirSync(absDir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        const abs = join(absDir, e.name);
+        if (e.isDirectory()) walk(abs);
+        else if (e.isFile()) out.push(relative(this.dir, abs).split(sep).join('/'));
+      }
+    };
+    walk(base);
+    return out.sort();
+  }
+
+  // ── Export / Import ─────────────────────────────────────────────────────────
+
+  /**
+   * Bundle the entire agent directory into a gzipped tar Buffer.
+   * Round-trips with `importBundle` / `AgentFs.fromBundle`.
+   */
+  exportBundle() {
+    const files = this.listFiles('.');
+    const entries = files.map((name) => ({
+      name,
+      data: readFileSync(join(this.dir, name.split('/').join(sep))),
+    }));
+    return packTarGz(entries);
+  }
+
+  /**
+   * Write the contents of a bundle into this agent directory.
+   * @param {Buffer} bundle
+   * @param {{ overwrite?: boolean }} [opts] overwrite existing files (default true)
+   */
+  importBundle(bundle, { overwrite = true } = {}) {
+    const entries = unpackTarGz(bundle);
+    mkdirSync(this.dir, { recursive: true });
+    let written = 0;
+    for (const { name, data } of entries) {
+      const rel = safeRelative(name);
+      const abs = join(this.dir, rel);
+      if (!overwrite && existsSync(abs)) continue;
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, data);
+      written++;
+    }
+    return { written, total: entries.length };
+  }
+
+  /** Rehydrate an agent from a bundle at a target root/agentId. */
+  static fromBundle(bundle, { root, agentId, overwrite = true } = {}) {
+    let id = agentId;
+    if (!id) {
+      // Infer agentId from the bundle's manifest if not provided.
+      const entries = unpackTarGz(bundle);
+      const manifest = entries.find((e) => e.name === MANIFEST_FILE);
+      if (manifest) {
+        try { id = JSON.parse(manifest.data.toString('utf-8')).agentId; } catch { /* ignore */ }
+      }
+    }
+    if (!id) throw new Error('agentfs: agentId required (not found in bundle manifest)');
+    const fs = new AgentFs({ root, agentId: id });
+    fs.importBundle(bundle, { overwrite });
+    return fs;
+  }
+}
+
+/** Convenience factory: build and `ensure()` an agent filesystem. */
+export function createAgentFs(opts) {
+  return new AgentFs(opts).ensure();
+}

package/src/asyncAgentfs.js

@@ -0,0 +1,153 @@
+/**
+ * AsyncAgentFs — the AgentFs model (layers + manifest + portable bundles) over
+ * a pluggable async StorageAdapter (see storage.js).
+ *
+ * Same concepts as the sync, disk-only AgentFs: a per-agent home with fixed
+ * layers, a manifest.json, safe agent-relative paths, and `.tar.gz`
+ * export/import round-trips. The storage backend is injected, so the same
+ * agent home can live on disk, in memory, or in a database — the platform's
+ * Supabase adapter (mounaji-backendv3 `agent_fs_nodes`) implements the same
+ * contract server-side.
+ */
+import { join, relative, isAbsolute } from 'node:path';
+import { DEFAULT_LAYERS } from './agentfs.js';
+import { packTarGz, unpackTarGz } from './tar.js';
+
+const MANIFEST_FILE = 'manifest.json';
+const MANIFEST_VERSION = 1;
+
+/** Normalize an agent-relative path and guard against escaping the agent home. */
+function safeRelative(relPath) {
+  const normalized = String(relPath).replace(/\\/g, '/').replace(/^\/+/, '');
+  const joined = join('/agent-root', normalized);
+  const rel = relative('/agent-root', joined);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`agentfs: path escapes agent directory: "${relPath}"`);
+  }
+  return normalized;
+}
+
+export class AsyncAgentFs {
+  /**
+   * @param {{ agentId: string, storage: object, layers?: string[] }} opts
+   *   storage — a StorageAdapter (read/write/remove/list/exists)
+   */
+  constructor({ agentId, storage, layers } = {}) {
+    if (!agentId || typeof agentId !== 'string') {
+      throw new Error('agentfs: agentId is required');
+    }
+    if (!storage || typeof storage.read !== 'function') {
+      throw new Error('agentfs: a StorageAdapter is required (see storage.js)');
+    }
+    this.agentId = agentId;
+    this.storage = storage;
+    this.layers = layers && layers.length ? [...layers] : [...DEFAULT_LAYERS];
+  }
+
+  /** Write the manifest if missing. Idempotent. */
+  async ensure() {
+    if (!(await this.storage.exists(MANIFEST_FILE))) {
+      const now = new Date().toISOString();
+      await this.writeManifest({
+        agentId: this.agentId,
+        version: MANIFEST_VERSION,
+        createdAt: now,
+        updatedAt: now,
+        layers: this.layers,
+        custom: {},
+      });
+    }
+    return this;
+  }
+
+  // ── Manifest ───────────────────────────────────────────────────────────────
+
+  async readManifest() {
+    const raw = await this.storage.read(MANIFEST_FILE);
+    if (raw == null) return null;
+    try {
+      return JSON.parse(raw.toString('utf-8'));
+    } catch {
+      return null;
+    }
+  }
+
+  async writeManifest(manifest) {
+    await this.storage.write(MANIFEST_FILE, JSON.stringify(manifest, null, 2));
+    return manifest;
+  }
+
+  async patchManifest(patch) {
+    const current = (await this.readManifest())
+      || { agentId: this.agentId, version: MANIFEST_VERSION, custom: {} };
+    const next = { ...current, ...patch, updatedAt: new Date().toISOString() };
+    return this.writeManifest(next);
+  }
+
+  // ── File operations (agent-relative paths) ──────────────────────────────────
+
+  async exists(relPath) {
+    return this.storage.exists(safeRelative(relPath));
+  }
+
+  async writeFile(relPath, content) {
+    await this.storage.write(safeRelative(relPath), content);
+  }
+
+  async readFile(relPath, encoding = 'utf-8') {
+    const raw = await this.storage.read(safeRelative(relPath));
+    if (raw == null) throw new Error(`agentfs: not found: "${relPath}"`);
+    return encoding ? raw.toString(encoding) : raw;
+  }
+
+  async writeJson(relPath, data) {
+    return this.writeFile(relPath, JSON.stringify(data, null, 2));
+  }
+
+  async readJson(relPath, fallback = null) {
+    try {
+      return JSON.parse(await this.readFile(relPath));
+    } catch {
+      return fallback;
+    }
+  }
+
+  async remove(relPath) {
+    await this.storage.remove(safeRelative(relPath));
+  }
+
+  async listFiles(relDir = '') {
+    return this.storage.list(relDir ? safeRelative(relDir) : '');
+  }
+
+  // ── Export / Import (same bundle format as the sync AgentFs) ───────────────
+
+  async exportBundle() {
+    const files = await this.listFiles('');
+    const entries = [];
+    for (const name of files) {
+      const data = await this.storage.read(name);
+      if (data != null) {
+        entries.push({ name, data: Buffer.isBuffer(data) ? data : Buffer.from(String(data)) });
+      }
+    }
+    return packTarGz(entries);
+  }
+
+  async importBundle(bundle, { overwrite = true } = {}) {
+    const entries = unpackTarGz(bundle);
+    let written = 0;
+    for (const { name, data } of entries) {
+      const rel = safeRelative(name);
+      if (!overwrite && (await this.storage.exists(rel))) continue;
+      await this.storage.write(rel, data);
+      written++;
+    }
+    return { written, total: entries.length };
+  }
+}
+
+/** Convenience factory: build and `ensure()` an async agent filesystem. */
+export async function createAsyncAgentFs(opts) {
+  return new AsyncAgentFs(opts).ensure();
+}

package/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * @mounaji_npm/agentfs — per-agent portable filesystem.
+ *
+ * @example
+ *   import { createAgentFs, AgentFs } from '@mounaji_npm/agentfs';
+ *
+ *   const fs = createAgentFs({ root: '/data/agents', agentId: 'abc123' });
+ *   fs.writeJson('memory/facts.json', { likes: ['dark mode'] });
+ *   fs.appendFile('learning/feedback_log.jsonl', JSON.stringify({ ok: true }) + '\n');
+ *
+ *   const bundle = fs.exportBundle();            // Buffer (.tar.gz)
+ *   const clone = AgentFs.fromBundle(bundle, { root: '/tmp', agentId: 'abc123' });
+ */
+export { AgentFs, createAgentFs, DEFAULT_LAYERS } from './agentfs.js';
+export { AsyncAgentFs, createAsyncAgentFs } from './asyncAgentfs.js';
+export { MemoryStorageAdapter, DiskStorageAdapter } from './storage.js';
+export { packTar, unpackTar, packTarGz, unpackTarGz } from './tar.js';

package/src/storage.js

@@ -0,0 +1,114 @@
+/**
+ * StorageAdapter — pluggable backends for AsyncAgentFs.
+ *
+ * The sync AgentFs class (agentfs.js) is disk-only by design. AsyncAgentFs
+ * (asyncAgentfs.js) talks to any backend through this minimal async contract,
+ * so the same layered agent home can live on local disk, in memory (tests),
+ * or in a database (e.g. the platform's Supabase `agent_fs_nodes` adapter).
+ *
+ * Contract (all paths are agent-relative, forward slashes, already sanitized
+ * by AsyncAgentFs — adapters never see `..`):
+ *   read(path)            → Promise<Buffer|string|null>   null when missing
+ *   write(path, data)     → Promise<void>                 creates parents
+ *   remove(path)          → Promise<void>                 recursive, tolerant
+ *   list(prefix)          → Promise<string[]>             file paths under prefix
+ *   exists(path)          → Promise<boolean>
+ */
+import { join, dirname, sep, relative } from 'node:path';
+import {
+  mkdirSync, existsSync, readFileSync, writeFileSync, rmSync,
+  readdirSync,
+} from 'node:fs';
+
+/** In-memory adapter — reference implementation and test double. */
+export class MemoryStorageAdapter {
+  constructor() {
+    this.files = new Map(); // path → Buffer
+  }
+
+  async read(path) {
+    return this.files.has(path) ? this.files.get(path) : null;
+  }
+
+  async write(path, data) {
+    this.files.set(path, Buffer.isBuffer(data) ? data : Buffer.from(String(data)));
+  }
+
+  async remove(path) {
+    this.files.delete(path);
+    const prefix = `${path}/`;
+    for (const key of [...this.files.keys()]) {
+      if (key.startsWith(prefix)) this.files.delete(key);
+    }
+  }
+
+  async list(prefix = '') {
+    const normalized = prefix && !prefix.endsWith('/') ? `${prefix}/` : prefix;
+    return [...this.files.keys()]
+      .filter((k) => !normalized || k.startsWith(normalized))
+      .sort();
+  }
+
+  async exists(path) {
+    if (this.files.has(path)) return true;
+    const prefix = `${path}/`;
+    for (const key of this.files.keys()) {
+      if (key.startsWith(prefix)) return true;
+    }
+    return false;
+  }
+}
+
+/** Disk adapter — same layout as the sync AgentFs (a base directory). */
+export class DiskStorageAdapter {
+  /** @param {{ baseDir: string }} opts absolute directory holding this agent */
+  constructor({ baseDir }) {
+    if (!baseDir) throw new Error('agentfs: DiskStorageAdapter requires baseDir');
+    this.baseDir = baseDir;
+  }
+
+  _abs(path) {
+    return join(this.baseDir, path.split('/').join(sep));
+  }
+
+  async read(path) {
+    try {
+      return readFileSync(this._abs(path));
+    } catch {
+      return null;
+    }
+  }
+
+  async write(path, data) {
+    const abs = this._abs(path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, data);
+  }
+
+  async remove(path) {
+    rmSync(this._abs(path), { recursive: true, force: true });
+  }
+
+  async list(prefix = '') {
+    const out = [];
+    const walk = (absDir) => {
+      let entries;
+      try {
+        entries = readdirSync(absDir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        const abs = join(absDir, e.name);
+        if (e.isDirectory()) walk(abs);
+        else if (e.isFile()) out.push(relative(this.baseDir, abs).split(sep).join('/'));
+      }
+    };
+    walk(prefix ? this._abs(prefix) : this.baseDir);
+    return out.sort();
+  }
+
+  async exists(path) {
+    return existsSync(this._abs(path));
+  }
+}

package/src/tar.js

@@ -0,0 +1,135 @@
+/**
+ * Minimal, dependency-free tar (ustar) + gzip writer/reader.
+ *
+ * We roll our own instead of pulling `tar`/`jszip` so `@mounaji_npm/agentfs`
+ * stays dependency-light like the rest of the monorepo. Scope is intentionally
+ * narrow: regular files only (no symlinks/devices), which is all an agent's
+ * layered home needs. Produces standard `.tar.gz` archives that `tar -xzf`
+ * (and any tar library) can read.
+ */
+import { gzipSync, gunzipSync } from 'node:zlib';
+
+const BLOCK = 512;
+
+/** Write a string into `buf` at `offset`, at most `len` bytes, NUL-padded. */
+function writeField(buf, str, offset, len) {
+  const bytes = Buffer.from(String(str), 'utf-8');
+  if (bytes.length > len) {
+    throw new Error(`tar field overflow (${bytes.length} > ${len}): "${str}"`);
+  }
+  bytes.copy(buf, offset);
+}
+
+/** Octal-encode `num` into a fixed-width field: (len-1) digits + NUL. */
+function octalField(num, len) {
+  return num.toString(8).padStart(len - 1, '0') + '\0';
+}
+
+/** Read a NUL-terminated string from a header field. */
+function readField(buf, offset, len) {
+  let end = offset;
+  const limit = offset + len;
+  while (end < limit && buf[end] !== 0) end++;
+  return buf.toString('utf-8', offset, end);
+}
+
+/**
+ * Split a path longer than 100 bytes into ustar {prefix, name}. Returns null
+ * if it cannot be represented (name > 100 or prefix > 155 with no clean split).
+ */
+function splitName(path) {
+  const full = Buffer.from(path, 'utf-8');
+  if (full.length <= 100) return { name: path, prefix: '' };
+  // Find a '/' such that the tail (name) is <= 100 bytes and head (prefix) <= 155.
+  for (let i = path.length - 1; i > 0; i--) {
+    if (path[i] !== '/') continue;
+    const name = path.slice(i + 1);
+    const prefix = path.slice(0, i);
+    if (Buffer.byteLength(name) <= 100 && Buffer.byteLength(prefix) <= 155) {
+      return { name, prefix };
+    }
+  }
+  return null;
+}
+
+/** Build a single 512-byte ustar header for a regular file. */
+function makeHeader({ name, prefix, size, mtime }) {
+  const h = Buffer.alloc(BLOCK);
+  writeField(h, name, 0, 100);
+  writeField(h, '0000644\0', 100, 8); // mode: rw-r--r--
+  writeField(h, octalField(0, 8), 108, 8); // uid
+  writeField(h, octalField(0, 8), 116, 8); // gid
+  writeField(h, octalField(size, 12), 124, 12);
+  writeField(h, octalField(mtime, 12), 136, 12);
+  h.fill(0x20, 148, 156); // checksum placeholder: 8 spaces
+  writeField(h, '0', 156, 1); // typeflag: regular file
+  writeField(h, 'ustar\0', 257, 6);
+  writeField(h, '00', 263, 2);
+  if (prefix) writeField(h, prefix, 345, 155);
+
+  let sum = 0;
+  for (let i = 0; i < BLOCK; i++) sum += h[i];
+  // Checksum field: 6 octal digits, NUL, space.
+  writeField(h, sum.toString(8).padStart(6, '0') + '\0 ', 148, 8);
+  return h;
+}
+
+/**
+ * Pack an array of `{ name, data }` (data: Buffer|string) into a tar buffer.
+ */
+export function packTar(entries) {
+  const mtime = Math.floor(Date.now() / 1000);
+  const chunks = [];
+  for (const entry of entries) {
+    const data = Buffer.isBuffer(entry.data) ? entry.data : Buffer.from(entry.data ?? '', 'utf-8');
+    const split = splitName(entry.name.replace(/\\/g, '/'));
+    if (!split) throw new Error(`tar: path too long to encode: "${entry.name}"`);
+    chunks.push(makeHeader({ name: split.name, prefix: split.prefix, size: data.length, mtime }));
+    chunks.push(data);
+    const pad = (BLOCK - (data.length % BLOCK)) % BLOCK;
+    if (pad) chunks.push(Buffer.alloc(pad));
+  }
+  // Two zero blocks terminate the archive.
+  chunks.push(Buffer.alloc(BLOCK * 2));
+  return Buffer.concat(chunks);
+}
+
+/** Parse a tar buffer into an array of `{ name, data }` (regular files only). */
+export function unpackTar(buf) {
+  const files = [];
+  let off = 0;
+  while (off + BLOCK <= buf.length) {
+    const header = buf.subarray(off, off + BLOCK);
+    // A full zero block marks the end of the archive.
+    let allZero = true;
+    for (let i = 0; i < BLOCK; i++) {
+      if (header[i] !== 0) { allZero = false; break; }
+    }
+    if (allZero) break;
+
+    const name = readField(header, 0, 100);
+    const prefix = readField(header, 345, 155);
+    const size = parseInt(readField(header, 124, 12).trim() || '0', 8) || 0;
+    const type = String.fromCharCode(header[156] || 0x30);
+    off += BLOCK;
+
+    const data = Buffer.from(buf.subarray(off, off + size));
+    // typeflag '0' or NUL (0x00 → '\0') means regular file; skip others.
+    if (type === '0' || type === '\0') {
+      const full = prefix ? `${prefix}/${name}` : name;
+      files.push({ name: full, data });
+    }
+    off += Math.ceil(size / BLOCK) * BLOCK;
+  }
+  return files;
+}
+
+/** Pack + gzip: `{ name, data }[]` → gzipped tar Buffer. */
+export function packTarGz(entries) {
+  return gzipSync(packTar(entries));
+}
+
+/** Gunzip + unpack: gzipped tar Buffer → `{ name, data }[]`. */
+export function unpackTarGz(buf) {
+  return unpackTar(gunzipSync(buf));
+}