@storyshelf/storage-local 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @storyshelf/storage-local
+
+The default storage adapter for self-hosted StoryShelf: reads and writes blobs to the local filesystem under a data directory. One `docker run` to self-host.
+
+## Install
+
+```sh
+nub add @storyshelf/storage-local
+```
+
+or
+
+```sh
+npm install @storyshelf/storage-local
+```
+
+## Quick start
+
+```ts
+import { createLocalStorage } from "@storyshelf/storage-local";
+import { createShelfRouter } from "@storyshelf/core";
+import { createSqliteDatabase } from "@storyshelf/db-sqlite";
+
+const storage = createLocalStorage("./data");
+const database = createSqliteDatabase("./data/shelf.db");
+
+const app = createShelfRouter({ database, storage });
+```
+
+## API
+
+### `createLocalStorage(dataDir: string): StorageAdapter`
+
+Stores all blobs under the resolved `dataDir` (creating directories as needed). Paths are confined to the data directory — any path escaping it throws an error.
+
+The returned adapter implements every method of the `StorageAdapter` interface (`read`, `write`, `delete`, `exists`, `list(prefix)`).
+
+## How it fits in
+
+`storage-local` is the default `storage` option for `createShelfRouter` in single-node deployments, storing screenshots, diff overlays, and storybook archives on disk. It implements the same `StorageAdapter` interface as `@storyshelf/storage-s3`, so moving to object storage later is a drop-in swap.
+
+See `docs/architecture.md` and ADR 0006.

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { StorageAdapter } from "@storyshelf/core/adapter/storage";
+//#region src/index.d.ts
+/**
+ * Create a local filesystem-backed StorageAdapter rooted at the given directory.
+ *
+ * @param dataDir - Root directory in which all stored files live.
+ * @returns A StorageAdapter that reads and writes files under `dataDir`.
+ */
+declare function createLocalStorage(dataDir: string): StorageAdapter;
+//#endregion
+export { createLocalStorage };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,68 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+//#region src/index.ts
+async function pathExists(target) {
+	try {
+		await access(target);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Create a local filesystem-backed StorageAdapter rooted at the given directory.
+*
+* @param dataDir - Root directory in which all stored files live.
+* @returns A StorageAdapter that reads and writes files under `dataDir`.
+*/
+function createLocalStorage(dataDir) {
+	const root = resolve(dataDir);
+	function toAbsolute(path) {
+		const target = resolve(root, path);
+		const rel = relative(root, target);
+		if (rel === ".." || rel.startsWith(`..${sep}`)) throw new Error(`Path escapes storage directory: ${path}`);
+		return target;
+	}
+	async function walk(dir) {
+		const entries = await readdir(dir, { withFileTypes: true });
+		return (await Promise.all(entries.map(async (entry) => {
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) return await walk(full);
+			return [relative(root, full)];
+		}))).flat();
+	}
+	return {
+		metadata: {
+			name: "Local Storage",
+			version: "0.1.0",
+			description: "Local filesystem storage adapter",
+			kind: "local"
+		},
+		async read(path) {
+			return await readFile(toAbsolute(path));
+		},
+		async write(path, data) {
+			const target = toAbsolute(path);
+			await mkdir(dirname(target), { recursive: true });
+			await writeFile(target, data);
+		},
+		async delete(path) {
+			await rm(toAbsolute(path), { force: true });
+		},
+		async exists(path) {
+			return await pathExists(toAbsolute(path));
+		},
+		async list(prefix) {
+			const dir = toAbsolute(prefix);
+			if (!await pathExists(dir)) return [];
+			return walk(dir);
+		}
+	};
+}
+//#endregion
+export { createLocalStorage };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { access, mkdir, readdir, readFile, rm, writeFile } from \"node:fs/promises\";\nimport { dirname, join, relative, resolve, sep } from \"node:path\";\n\nimport type { StorageAdapter } from \"@storyshelf/core/adapter/storage\";\n\ndeclare const __PKG_VERSION__: string;\n\nasync function pathExists(target: string): Promise<boolean> {\n  try {\n    await access(target);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Create a local filesystem-backed StorageAdapter rooted at the given directory.\n *\n * @param dataDir - Root directory in which all stored files live.\n * @returns A StorageAdapter that reads and writes files under `dataDir`.\n */\nexport function createLocalStorage(dataDir: string): StorageAdapter {\n  const root = resolve(dataDir);\n\n  function toAbsolute(path: string): string {\n    const target = resolve(root, path);\n    const rel = relative(root, target);\n    if (rel === \"..\" || rel.startsWith(`..${sep}`)) {\n      throw new Error(`Path escapes storage directory: ${path}`);\n    }\n    return target;\n  }\n\n  async function walk(dir: string): Promise<string[]> {\n    const entries = await readdir(dir, { withFileTypes: true });\n    const nested = await Promise.all(\n      entries.map(async (entry) => {\n        const full = join(dir, entry.name);\n        if (entry.isDirectory()) {\n          return await walk(full);\n        }\n        return [relative(root, full)];\n      }),\n    );\n    return nested.flat();\n  }\n\n  return {\n    metadata: {\n      name: \"Local Storage\",\n      version: typeof __PKG_VERSION__ === \"undefined\" ? \"0.0.0\" : __PKG_VERSION__, // oxlint-disable-line unicorn/no-typeof-undefined\n      description: \"Local filesystem storage adapter\",\n      kind: \"local\",\n    },\n    async read(path) {\n      return await readFile(toAbsolute(path));\n    },\n    async write(path, data) {\n      const target = toAbsolute(path);\n      await mkdir(dirname(target), { recursive: true });\n      await writeFile(target, data);\n    },\n    async delete(path) {\n      await rm(toAbsolute(path), { force: true });\n    },\n    async exists(path) {\n      return await pathExists(toAbsolute(path));\n    },\n    async list(prefix) {\n      const dir = toAbsolute(prefix);\n      if (!(await pathExists(dir))) {\n        return [];\n      }\n      return walk(dir);\n    },\n  };\n}\n"],"mappings":";;;;;;AAOA,eAAe,WAAW,QAAkC;CAC1D,IAAI;EACF,MAAM,OAAO,MAAM;EACnB,OAAO;CACT,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;AAQA,SAAgB,mBAAmB,SAAiC;CAClE,MAAM,OAAO,QAAQ,OAAO;CAE5B,SAAS,WAAW,MAAsB;EACxC,MAAM,SAAS,QAAQ,MAAM,IAAI;EACjC,MAAM,MAAM,SAAS,MAAM,MAAM;EACjC,IAAI,QAAQ,QAAQ,IAAI,WAAW,KAAK,KAAK,GAC3C,MAAM,IAAI,MAAM,mCAAmC,MAAM;EAE3D,OAAO;CACT;CAEA,eAAe,KAAK,KAAgC;EAClD,MAAM,UAAU,MAAM,QAAQ,KAAK,EAAE,eAAe,KAAK,CAAC;EAU1D,QAAO,MATc,QAAQ,IAC3B,QAAQ,IAAI,OAAO,UAAU;GAC3B,MAAM,OAAO,KAAK,KAAK,MAAM,IAAI;GACjC,IAAI,MAAM,YAAY,GACpB,OAAO,MAAM,KAAK,IAAI;GAExB,OAAO,CAAC,SAAS,MAAM,IAAI,CAAC;EAC9B,CAAC,CACH,EAAA,CACc,KAAK;CACrB;CAEA,OAAO;EACL,UAAU;GACR,MAAM;GACN,SAAA;GACA,aAAa;GACb,MAAM;EACR;EACA,MAAM,KAAK,MAAM;GACf,OAAO,MAAM,SAAS,WAAW,IAAI,CAAC;EACxC;EACA,MAAM,MAAM,MAAM,MAAM;GACtB,MAAM,SAAS,WAAW,IAAI;GAC9B,MAAM,MAAM,QAAQ,MAAM,GAAG,EAAE,WAAW,KAAK,CAAC;GAChD,MAAM,UAAU,QAAQ,IAAI;EAC9B;EACA,MAAM,OAAO,MAAM;GACjB,MAAM,GAAG,WAAW,IAAI,GAAG,EAAE,OAAO,KAAK,CAAC;EAC5C;EACA,MAAM,OAAO,MAAM;GACjB,OAAO,MAAM,WAAW,WAAW,IAAI,CAAC;EAC1C;EACA,MAAM,KAAK,QAAQ;GACjB,MAAM,MAAM,WAAW,MAAM;GAC7B,IAAI,CAAE,MAAM,WAAW,GAAG,GACxB,OAAO,CAAC;GAEV,OAAO,KAAK,GAAG;EACjB;CACF;AACF"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@storyshelf/storage-local",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Local filesystem storage adapter for StoryShelf.",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/storyshelf.git",
+    "directory": "packages/storage-local"
+  },
+  "homepage": "https://github.com/GuptaSiddhant/storyshelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/storyshelf/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt -c ../../.oxfmtrc.json ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "vitest run",
+    "prepublishOnly": "nub run build"
+  },
+  "dependencies": {
+    "@storyshelf/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "oxfmt": "catalog:",
+    "oxlint": "catalog:",
+    "oxlint-tsgolint": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  }
+}