md-bundle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Holden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# md-bundle
+
+A Markdown bundle is a root Markdown file plus optional related files in the
+same folder tree, addressed by bundle-relative paths.
+
+The root file stays the entry point. Supporting Markdown files, scripts, and
+assets let the bundle grow by progressive disclosure instead of becoming one
+giant document.
+
+An [agent skill](https://agentskills.io/) is one example of a Markdown bundle:
+`SKILL.md` is the root file, while references, scripts, and assets can live
+beside it. `md-bundle` makes that folder shape reusable for skills, agent
+instructions, docs, specs, and other Markdown artifacts.
+
+## Install
+
+```sh
+npm install md-bundle
+```
+
+## Example
+
+```txt
+my-skill/
+  SKILL.md
+  references/checklist.md
+  assets/logo.png
+```
+
+```ts
+import { getTextFile, loadBundle } from "md-bundle";
+
+const bundle = await loadBundle("my-skill/SKILL.md");
+
+const root = bundle.root.content;
+const checklist = getTextFile(bundle, "references/checklist.md");
+```
+
+## Bundle Model
+
+A bundle has one root Markdown file and zero or more related files beside it.
+
+```ts
+type MarkdownBundle = {
+  root: MarkdownBundleTextFile;
+  files: MarkdownBundleFile[];
+};
+
+type MarkdownBundleFile = MarkdownBundleTextFile | MarkdownBundleBinaryFile;
+
+type MarkdownBundleTextFile = {
+  path: string;
+  content: string;
+};
+
+type MarkdownBundleBinaryFile = {
+  path: string;
+  bytes: Uint8Array;
+};
+```
+
+```txt
+SKILL.md
+references/checklist.md
+assets/logo.png
+```
+
+`root` is the text file clients should read first. `files` contains the complete
+bundle, including the root file.
+
+Files are addressed by paths relative to the bundle directory. Text files store
+`content`. Binary files store `bytes`.
+
+## API Reference
+
+### Load
+
+```ts
+loadBundle(path, { rootPath }?);
+```
+
+Reads a bundle from a root Markdown file or directory.
+
+When `path` is a file, that file is the bundle root and its parent directory is
+the bundle directory. When `path` is a directory, `rootPath` can identify the
+root file. If omitted, `loadBundle` tries to infer it.
+
+### Create
+
+```ts
+createBundle({ rootPath, files });
+```
+
+Creates a normalized bundle from in-memory files.
+
+### Get Files
+
+- `getFile(bundle, bundlePath)`: returns a text or binary file.
+- `getTextFile(bundle, bundlePath)`: returns a text file.
+- `getBinaryFile(bundle, bundlePath)`: returns a binary file.
+
+### File Guards
+
+```ts
+isTextFile(file);
+isBinaryFile(file);
+isMarkdownFile(file);
+```
+
+These narrow `MarkdownBundleFile` when filtering or branching on file type.
+
+### Bundle References
+
+```ts
+resolveBundleReference(fromPath, referencePath);
+```
+
+Resolves a reference written in one bundle file to a normalized bundle path.
+
+```ts
+resolveBundleReference("docs/index.md", "./intro.md");
+// "docs/intro.md"
+```
+
+```ts
+formatBundleReference(fromPath, targetPath);
+```
+
+Formats a bundle path as a relative reference from one file to another.
+
+```ts
+formatBundleReference("docs/index.md", "assets/logo.png");
+// "../assets/logo.png"
+```
+
+### Write
+
+```ts
+writeBundle(bundle, directory);
+```
+
+Writes bundle files into `directory`, preserving bundle-relative paths.
+
+### Errors
+
+Expected failures throw `MarkdownBundleError` with a stable `code`.
+
+```ts
+class MarkdownBundleError extends Error {
+  code: string;
+}
+```
+
+## Spec
+
+See [SPEC.md](./SPEC.md) for precise behavior around path normalization, root
+inference, loading, references, and writing.

package/SPEC.md

@@ -0,0 +1,41 @@
+# md-bundle spec
+
+This spec defines behavior that is intentionally more precise than the README.
+
+## Bundle Model
+
+- Files are sorted lexicographically by path.
+
+## Paths
+
+- Bundle paths use `/` and are relative to the bundle directory.
+- Stored file paths cannot be empty, absolute, or escape the bundle.
+- `.` and `..` segments are resolved before storage.
+
+## Construction
+
+- `rootPath` must identify one text `.md` file in `files`.
+- File paths must be valid and unique.
+
+## Loading
+
+- Without `rootPath`, loading infers the root from top-level Markdown files:
+  the only `.md` file, otherwise `SKILL.md`, otherwise `index.md`.
+- Missing or ambiguous roots fail.
+- Loading skips `.git` directories and does not follow symlinks.
+- Valid UTF-8 files load as text; non-UTF-8 files load as binary.
+
+## Bundle References
+
+- References resolve from the directory of the file that contains them.
+- References starting with `/` resolve from the bundle root.
+- Reference resolution can return `""` for the bundle root.
+- References cannot escape the bundle.
+- Resolution does not check target existence.
+- Formatted references are relative to the directory of the file that contains
+  them.
+
+## Writing
+
+- Parent directories are created, but existing output directories are not
+  deleted.

package/dist/bundle.d.ts

@@ -0,0 +1,26 @@
+import type { MarkdownBundle, MarkdownBundleBinaryFile, MarkdownBundleFile, MarkdownBundleTextFile } from "./types.js";
+/**
+ * Input accepted by `createBundle`.
+ */
+export type CreateBundleInput = {
+    /** Bundle path of the root Markdown file. */
+    rootPath: string;
+    /** Files to normalize into the bundle. */
+    files: MarkdownBundleFile[];
+};
+/**
+ * Create a normalized in-memory bundle.
+ */
+export declare function createBundle(input: CreateBundleInput): MarkdownBundle;
+/**
+ * Get any bundle file by path.
+ */
+export declare function getFile(bundle: MarkdownBundle, bundlePath: string): MarkdownBundleFile;
+/**
+ * Get a text bundle file by path.
+ */
+export declare function getTextFile(bundle: MarkdownBundle, bundlePath: string): MarkdownBundleTextFile;
+/**
+ * Get a binary bundle file by path.
+ */
+export declare function getBinaryFile(bundle: MarkdownBundle, bundlePath: string): MarkdownBundleBinaryFile;

package/dist/bundle.js

@@ -0,0 +1,73 @@
+import { fail } from "./error.js";
+import { compareBundlePaths, normalizeBundleFilePath } from "./paths.js";
+/**
+ * Create a normalized in-memory bundle.
+ */
+export function createBundle(input) {
+    const rootPath = normalizeBundleFilePath(input.rootPath);
+    const seen = new Set();
+    const files = [];
+    for (const inputFile of input.files) {
+        const file = normalizeInputFile(inputFile);
+        if (seen.has(file.path)) {
+            fail("FILE_DUPLICATE", `Duplicate bundle file: ${file.path}`);
+        }
+        seen.add(file.path);
+        files.push(file);
+    }
+    const sortedFiles = files.sort((left, right) => compareBundlePaths(left.path, right.path));
+    const root = sortedFiles.find((file) => isTextFile(file) && file.path === rootPath && file.path.endsWith(".md"));
+    if (root === undefined) {
+        const matchingFile = sortedFiles.find((file) => file.path === rootPath);
+        if (matchingFile === undefined) {
+            fail("ROOT_MISSING", `Bundle root does not exist: ${rootPath}`);
+        }
+        fail("ROOT_INVALID", `Bundle root must be a text Markdown file: ${rootPath}`);
+    }
+    return { root, files: sortedFiles };
+}
+/**
+ * Get any bundle file by path.
+ */
+export function getFile(bundle, bundlePath) {
+    const normalized = normalizeBundleFilePath(bundlePath);
+    const file = bundle.files.find((item) => item.path === normalized);
+    return file === undefined
+        ? fail("FILE_MISSING", `Bundle file does not exist: ${normalized}`)
+        : file;
+}
+/**
+ * Get a text bundle file by path.
+ */
+export function getTextFile(bundle, bundlePath) {
+    const file = getFile(bundle, bundlePath);
+    return isTextFile(file) ? file : fail("FILE_NOT_TEXT", `Bundle file is not text: ${file.path}`);
+}
+/**
+ * Get a binary bundle file by path.
+ */
+export function getBinaryFile(bundle, bundlePath) {
+    const file = getFile(bundle, bundlePath);
+    return isBinaryFile(file)
+        ? file
+        : fail("FILE_NOT_BINARY", `Bundle file is not binary: ${file.path}`);
+}
+/**
+ * Normalize one caller-provided file into the stored bundle shape.
+ */
+function normalizeInputFile(file) {
+    const normalized = normalizeBundleFilePath(file.path);
+    if (isTextFile(file)) {
+        return { path: normalized, content: file.content };
+    }
+    if (isBinaryFile(file)) {
+        return { path: normalized, bytes: file.bytes };
+    }
+    fail("FILE_INVALID", `Invalid bundle file: ${file.path}`);
+}
+function isTextFile(file) {
+    return "content" in file && typeof file.content === "string" && !("bytes" in file);
+}
+function isBinaryFile(file) {
+    return "bytes" in file && file.bytes instanceof Uint8Array && !("content" in file);
+}

package/dist/error.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Error thrown by expected md-bundle failures.
+ */
+export declare class MarkdownBundleError<TCode extends string = string> extends Error {
+    /** Machine-readable error code. */
+    readonly code: TCode;
+    constructor(code: TCode, message: string);
+}
+/**
+ * Throw an expected md-bundle failure with a stable error code.
+ */
+export declare function fail<TCode extends string>(code: TCode, message: string): never;

package/dist/error.js

@@ -0,0 +1,18 @@
+/**
+ * Error thrown by expected md-bundle failures.
+ */
+export class MarkdownBundleError extends Error {
+    /** Machine-readable error code. */
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "MarkdownBundleError";
+        this.code = code;
+    }
+}
+/**
+ * Throw an expected md-bundle failure with a stable error code.
+ */
+export function fail(code, message) {
+    throw new MarkdownBundleError(code, message);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createBundle, getBinaryFile, getFile, getTextFile } from "./bundle.js";
+export { MarkdownBundleError } from "./error.js";
+export { loadBundle, writeBundle } from "./io.js";
+export { formatBundleReference, resolveBundleReference } from "./paths.js";
+export { isBinaryFile, isMarkdownFile, isTextFile } from "./types.js";
+export type { CreateBundleInput } from "./bundle.js";
+export type { LoadBundleOptions } from "./io.js";
+export type { MarkdownBundle, MarkdownBundleBinaryFile, MarkdownBundleFile, MarkdownBundleTextFile, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createBundle, getBinaryFile, getFile, getTextFile } from "./bundle.js";
+export { MarkdownBundleError } from "./error.js";
+export { loadBundle, writeBundle } from "./io.js";
+export { formatBundleReference, resolveBundleReference } from "./paths.js";
+export { isBinaryFile, isMarkdownFile, isTextFile } from "./types.js";

package/dist/io.d.ts

@@ -0,0 +1,13 @@
+import type { MarkdownBundle } from "./types.js";
+export type LoadBundleOptions = {
+    /** Bundle path of the root Markdown file. */
+    rootPath?: string;
+};
+/**
+ * Load a bundle from a root file or bundle directory.
+ */
+export declare function loadBundle(inputPath: string, options?: LoadBundleOptions): Promise<MarkdownBundle>;
+/**
+ * Write bundle files into a directory.
+ */
+export declare function writeBundle(bundle: MarkdownBundle, directory: string): Promise<void>;

package/dist/io.js

@@ -0,0 +1,123 @@
+import { lstat, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createBundle } from "./bundle.js";
+import { fail } from "./error.js";
+import { compareBundlePaths, normalizeBundleFilePath } from "./paths.js";
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Load a bundle from a root file or bundle directory.
+ */
+export async function loadBundle(inputPath, options = {}) {
+    let inputStats;
+    try {
+        inputStats = await lstat(inputPath);
+    }
+    catch {
+        fail("BUNDLE_LOAD_ERROR", `Could not read bundle path: ${inputPath}`);
+    }
+    if (inputStats.isSymbolicLink()) {
+        fail("BUNDLE_LOAD_ERROR", `Bundle path cannot be a symlink: ${inputPath}`);
+    }
+    if (!inputStats.isDirectory() && !inputStats.isFile()) {
+        fail("BUNDLE_LOAD_ERROR", `Bundle path is not a file or directory: ${inputPath}`);
+    }
+    const bundleDirectory = inputStats.isDirectory() ? inputPath : path.dirname(inputPath);
+    const defaultRootPath = inputStats.isFile()
+        ? path.basename(inputPath).replaceAll("\\", "/")
+        : undefined;
+    const files = await loadBundleFiles(bundleDirectory);
+    const rootPath = options.rootPath ?? defaultRootPath;
+    if (rootPath !== undefined) {
+        return createBundle({ rootPath, files });
+    }
+    const inferredRootPath = inferRootPath(files);
+    return createBundle({ rootPath: inferredRootPath, files });
+}
+/**
+ * Write bundle files into a directory.
+ */
+export async function writeBundle(bundle, directory) {
+    for (const file of bundle.files) {
+        const bundlePath = normalizeBundleFilePath(file.path);
+        const outputPath = path.join(directory, ...bundlePath.split("/"));
+        try {
+            await mkdir(path.dirname(outputPath), { recursive: true });
+            await writeFile(outputPath, isTextFile(file) ? file.content : file.bytes);
+        }
+        catch {
+            fail("BUNDLE_WRITE_ERROR", `Could not write bundle file: ${bundlePath}`);
+        }
+    }
+}
+/**
+ * Load every regular file below a bundle directory.
+ */
+async function loadBundleFiles(directory) {
+    const files = [];
+    async function visit(currentDirectory) {
+        let entries;
+        try {
+            entries = await readdir(currentDirectory, { withFileTypes: true });
+        }
+        catch {
+            fail("BUNDLE_LOAD_ERROR", `Could not read directory: ${currentDirectory}`);
+        }
+        for (const entry of entries.sort((left, right) => compareBundlePaths(left.name, right.name))) {
+            if ((entry.name === ".git" && entry.isDirectory()) || entry.isSymbolicLink())
+                continue;
+            const absolutePath = path.join(currentDirectory, entry.name);
+            if (entry.isDirectory()) {
+                await visit(absolutePath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            let bytes;
+            try {
+                bytes = await readFile(absolutePath);
+            }
+            catch {
+                fail("BUNDLE_LOAD_ERROR", `Could not read file: ${absolutePath}`);
+            }
+            const bundlePath = path.relative(directory, absolutePath).replaceAll("\\", "/");
+            const text = decodeUtf8(bytes);
+            files.push(text !== undefined
+                ? { path: bundlePath, content: text }
+                : { path: bundlePath, bytes: new Uint8Array(bytes) });
+        }
+    }
+    await visit(directory);
+    return files;
+}
+/**
+ * Infer a conventional root from top-level Markdown files.
+ */
+function inferRootPath(files) {
+    const topLevelMarkdown = files
+        .map((file) => normalizeBundleFilePath(file.path))
+        .filter((filePath) => !filePath.includes("/") && filePath.endsWith(".md"));
+    if (topLevelMarkdown.length === 1) {
+        return topLevelMarkdown[0];
+    }
+    if (topLevelMarkdown.includes("SKILL.md")) {
+        return "SKILL.md";
+    }
+    if (topLevelMarkdown.includes("index.md")) {
+        return "index.md";
+    }
+    fail(topLevelMarkdown.length === 0 ? "ROOT_MISSING" : "ROOT_AMBIGUOUS", "Could not infer bundle root. Pass an explicit rootPath.");
+}
+/**
+ * Decode bytes only when they are valid UTF-8.
+ */
+function decodeUtf8(bytes) {
+    try {
+        return textDecoder.decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isTextFile(file) {
+    return "content" in file;
+}

package/dist/paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Normalize a stored bundle file path, which cannot be the bundle root.
+ */
+export declare function normalizeBundleFilePath(filePath: string): string;
+/**
+ * Resolve a reference written in one bundle file to a bundle path.
+ */
+export declare function resolveBundleReference(fromPath: string, referencePath: string): string;
+/**
+ * Format a bundle path as a relative reference from one bundle file.
+ */
+export declare function formatBundleReference(fromPath: string, targetPath: string): string;
+/**
+ * Compare bundle paths with stable JavaScript string ordering.
+ */
+export declare function compareBundlePaths(left: string, right: string): number;

package/dist/paths.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { fail } from "./error.js";
+/**
+ * Normalize a stored bundle file path, which cannot be the bundle root.
+ */
+export function normalizeBundleFilePath(filePath) {
+    const normalized = normalizeBundlePath(filePath);
+    if (normalized === "") {
+        fail("PATH_INVALID", `Invalid bundle path: ${filePath}`);
+    }
+    return normalized;
+}
+/**
+ * Resolve a reference written in one bundle file to a bundle path.
+ */
+export function resolveBundleReference(fromPath, referencePath) {
+    if (referencePath === "") {
+        fail("PATH_INVALID", "Invalid bundle reference: empty path");
+    }
+    const from = normalizeBundleFilePath(fromPath);
+    const reference = referencePath.replaceAll("\\", "/");
+    const target = reference.startsWith("/")
+        ? reference.slice(1)
+        : path.posix.join(path.posix.dirname(from), reference);
+    return normalizeBundlePath(target);
+}
+/**
+ * Format a bundle path as a relative reference from one bundle file.
+ */
+export function formatBundleReference(fromPath, targetPath) {
+    const from = normalizeBundleFilePath(fromPath);
+    const target = normalizeBundleFilePath(targetPath);
+    const fromDirectory = path.posix.dirname(from);
+    const relative = path.posix.relative(fromDirectory === "." ? "" : fromDirectory, target);
+    return relative === "" ? path.posix.basename(target) : relative;
+}
+/**
+ * Compare bundle paths with stable JavaScript string ordering.
+ */
+export function compareBundlePaths(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+/**
+ * Normalize a bundle path that may point to the bundle root.
+ */
+function normalizeBundlePath(filePath) {
+    if (isAbsolutePath(filePath)) {
+        fail("PATH_INVALID", `Invalid bundle path: ${filePath}`);
+    }
+    const segments = [];
+    for (const segment of filePath.replaceAll("\\", "/").split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            if (segments.length === 0) {
+                fail("PATH_INVALID", `Invalid bundle path: ${filePath}`);
+            }
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    return segments.join("/");
+}
+function isAbsolutePath(filePath) {
+    return path.posix.isAbsolute(filePath) || path.win32.isAbsolute(filePath);
+}

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Folder-shaped collection of files with one root Markdown file.
+ */
+export type MarkdownBundle = {
+    /** Text file clients should read first. */
+    root: MarkdownBundleTextFile;
+    /** Complete bundle file list, including `root`. */
+    files: MarkdownBundleFile[];
+};
+/**
+ * File stored in a Markdown bundle.
+ */
+export type MarkdownBundleFile = MarkdownBundleTextFile | MarkdownBundleBinaryFile;
+/**
+ * Text file stored in a Markdown bundle.
+ */
+export type MarkdownBundleTextFile = {
+    /** Bundle-relative file path. */
+    path: string;
+    /** Text content. */
+    content: string;
+};
+/**
+ * Binary file stored in a Markdown bundle.
+ */
+export type MarkdownBundleBinaryFile = {
+    /** Bundle-relative file path. */
+    path: string;
+    /** Raw file bytes. */
+    bytes: Uint8Array;
+};
+/**
+ * Check whether a bundle file stores text content.
+ */
+export declare function isTextFile(file: MarkdownBundleFile): file is MarkdownBundleTextFile;
+/**
+ * Check whether a bundle file stores binary bytes.
+ */
+export declare function isBinaryFile(file: MarkdownBundleFile): file is MarkdownBundleBinaryFile;
+/**
+ * Check whether a bundle file is a Markdown text file.
+ */
+export declare function isMarkdownFile(file: MarkdownBundleFile): file is MarkdownBundleTextFile;

package/dist/types.js

@@ -0,0 +1,18 @@
+/**
+ * Check whether a bundle file stores text content.
+ */
+export function isTextFile(file) {
+    return "content" in file;
+}
+/**
+ * Check whether a bundle file stores binary bytes.
+ */
+export function isBinaryFile(file) {
+    return "bytes" in file;
+}
+/**
+ * Check whether a bundle file is a Markdown text file.
+ */
+export function isMarkdownFile(file) {
+    return isTextFile(file) && file.path.endsWith(".md");
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "md-bundle",
+  "version": "0.1.0",
+  "description": "Markdown bundles: one root Markdown file plus related docs, scripts, and assets.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holdenmatt/md-bundle.git"
+  },
+  "files": [
+    "dist",
+    "SPEC.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "vitest run",
+    "lint": "oxlint",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "check": "pnpm format:check && pnpm lint && pnpm test && pnpm build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "oxfmt": "^0.56.0",
+    "oxlint": "^1.71.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "packageManager": "pnpm@11.7.0"
+}