@camstack/system 1.0.2

package/dist/builtins/sqlite-storage/filesystem-storage-provider.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import { IStorageProviderImpl, StorageLocation, StorageProviderInfoSchema } from '@camstack/types';
+type StorageProviderInfo = z.infer<typeof StorageProviderInfoSchema>;
+export declare class FilesystemStorageProvider implements IStorageProviderImpl {
+    static readonly providerId = "filesystem-storage";
+    static readonly displayName = "Filesystem";
+    private readonly uploads;
+    private readonly downloads;
+    getProviderInfo(): Promise<StorageProviderInfo>;
+    testLocation({ config }: {
+        readonly config: Record<string, unknown>;
+    }): Promise<{
+        readonly ok: boolean;
+        readonly error?: string;
+    }>;
+    resolve({ location, relativePath, }: {
+        readonly location: StorageLocation;
+        readonly relativePath: string;
+    }): Promise<string>;
+    write({ location, relativePath, data, }: {
+        readonly location: StorageLocation;
+        readonly relativePath: string;
+        readonly data: Uint8Array;
+    }): Promise<void>;
+    read({ location, relativePath, }: {
+        readonly location: StorageLocation;
+        readonly relativePath: string;
+    }): Promise<Uint8Array<ArrayBuffer>>;
+    exists({ location, relativePath, }: {
+        readonly location: StorageLocation;
+        readonly relativePath: string;
+    }): Promise<boolean>;
+    list({ location, prefix, }: {
+        readonly location: StorageLocation;
+        readonly prefix?: string;
+    }): Promise<readonly string[]>;
+    delete({ location, relativePath, }: {
+        readonly location: StorageLocation;
+        readonly relativePath: string;
+    }): Promise<void>;
+    getAvailableSpace({ location, }: {
+        readonly location: StorageLocation;
+    }): Promise<number | null>;
+    beginUpload({ location, relativePath, }: {
+        readonly location: StorageLocation;
+        readonly relativePath: string;
+        readonly sizeBytes?: number;
+    }): Promise<{
+        readonly uploadId: string;
+    }>;
+    writeChunk({ uploadId, offset, data, }: {
+        readonly uploadId: string;
+        readonly offset: number;
+        readonly data: Uint8Array;
+    }): Promise<void>;
+    finalizeUpload({ uploadId }: {
+        readonly uploadId: string;
+    }): Promise<void>;
+    abortUpload({ uploadId }: {
+        readonly uploadId: string;
+    }): Promise<void>;
+    beginDownload({ location, relativePath, }: {
+        readonly location: StorageLocation;
+        readonly relativePath: string;
+    }): Promise<{
+        readonly downloadId: string;
+        readonly sizeBytes: number;
+    }>;
+    readChunk({ downloadId, offset, length, }: {
+        readonly downloadId: string;
+        readonly offset: number;
+        readonly length: number;
+    }): Promise<Uint8Array<ArrayBuffer>>;
+    endDownload({ downloadId }: {
+        readonly downloadId: string;
+    }): Promise<void>;
+    /**
+     * Abort all outstanding sessions. Called on addon shutdown so timers
+     * don't leak across hot-reload cycles.
+     */
+    dispose(): Promise<void>;
+}
+export default FilesystemStorageProvider;

package/dist/builtins/sqlite-storage/filesystem-storage.addon.d.ts

@@ -0,0 +1,32 @@
+import { ProviderRegistration, BaseAddon } from '@camstack/types';
+import { FilesystemStorageProvider } from './filesystem-storage-provider.js';
+interface FilesystemStorageConfig {
+    readonly rootPath: string;
+    readonly storageAllowedRoots: readonly string[];
+}
+/**
+ * Filesystem Storage addon — registers a filesystem-backed
+ * `storage-provider` (Task 7).
+ *
+ * Pre-Task 7 this addon registered against the (then-collection)
+ * `storage` cap. After Tasks 2/3/4 the consumer-facing `storage` cap is
+ * a singleton owned by `storage-orchestrator`; the orchestrator
+ * dispatches each call to whichever `storage-provider` matches
+ * `location.providerId`.
+ *
+ * The OLD `rootPath` config field is preserved for back-compat: the
+ * orchestrator's first-boot seeding step still uses the same env-var
+ * resolution chain (operator override → `CAMSTACK_DATA` → fallback) to
+ * derive the base path of every default location, then writes
+ * `config.basePath` into each persisted `StorageLocation` row. The
+ * provider itself is now stateless — every call carries the live
+ * `StorageLocation` inline.
+ */
+export declare class FilesystemStorageAddon extends BaseAddon<FilesystemStorageConfig> {
+    private provider;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    getProvider(): FilesystemStorageProvider | null;
+}
+export default FilesystemStorageAddon;

package/dist/builtins/sqlite-storage/filesystem-storage.addon.js

@@ -0,0 +1,396 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+const require_chunk = require("../../chunk-Cek0wNdY.js");
+let node_fs = require("node:fs");
+node_fs = require_chunk.__toESM(node_fs);
+let node_path = require("node:path");
+node_path = require_chunk.__toESM(node_path);
+let _camstack_types = require("@camstack/types");
+let node_crypto = require("node:crypto");
+let node_os = require("node:os");
+let node_fs_promises = require("node:fs/promises");
+//#region src/builtins/sqlite-storage/filesystem-storage-provider.ts
+/**
+* Filesystem `storage-provider` (Task 7).
+*
+* Implements the `storage-provider` collection cap. Replaces the legacy
+* sync `IStorageProvider` shape — every method now takes the live
+* `StorageLocation` inline (no per-provider location state) and works
+* off `location.config.basePath`.
+*
+* Adds chunked upload (`.partial` rename trick) + chunked download
+* sessions for moving multi-GB archives without buffering the whole
+* archive in memory. Sessions auto-expire after 5 minutes idle.
+*
+* The legacy `FilesystemStorageProvider` in `@camstack/types/node` is
+* deliberately untouched — it still backs the sync `ctx.kernel.storage`
+* helper that addons like `pipeline-analytics` use to derive paths
+* synchronously. That sync API will be retired in a later refactor;
+* Task 7 is scoped to the cap surface only.
+*/
+/** Idle TTL for upload + download sessions. */
+var SESSION_IDLE_TTL_MS = 300 * 1e3;
+/**
+* Resolve `location.config.basePath` into a string. Throws an actionable
+* error when the field is missing or wrong-typed — every primitive
+* funnels through here, so a missing field surfaces as a single clear
+* message instead of a downstream `path.join` TypeError.
+*/
+function getBasePath(location) {
+	const basePath = location.config["basePath"];
+	if (typeof basePath !== "string" || basePath.length === 0) throw new Error(`filesystem-storage: location "${location.id}" missing string config.basePath`);
+	return basePath;
+}
+/**
+* Resolve a relative path against the location's base, rejecting any
+* traversal that escapes the base directory. Mirrors the
+* `addon-asset` endpoint security check in `main.ts`: normalize both
+* the base + the joined target, then enforce `target.startsWith(base + sep)`
+* (with the `+ sep` guard so `/data` doesn't accidentally allow
+* `/datasecret`).
+*/
+function safeResolve(base, relativePath) {
+	const normalizedBase = node_path.resolve(base);
+	const target = node_path.resolve(normalizedBase, relativePath);
+	if (target !== normalizedBase && !target.startsWith(normalizedBase + node_path.sep)) throw new Error(`filesystem-storage: relativePath "${relativePath}" escapes basePath "${normalizedBase}"`);
+	return target;
+}
+var FilesystemStorageProvider = class FilesystemStorageProvider {
+	static providerId = "filesystem-storage";
+	static displayName = "Filesystem";
+	uploads = /* @__PURE__ */ new Map();
+	downloads = /* @__PURE__ */ new Map();
+	async getProviderInfo() {
+		return {
+			providerId: FilesystemStorageProvider.providerId,
+			displayName: FilesystemStorageProvider.displayName,
+			shouldSaveDiskSpace: true,
+			minFreePercent: 10,
+			nodeLocal: true,
+			configSchema: { sections: [{
+				id: "filesystem-storage",
+				title: "Filesystem",
+				fields: [{
+					type: "text",
+					key: "basePath",
+					label: "Base path",
+					description: "Absolute directory path where files are stored.",
+					required: true
+				}]
+			}] }
+		};
+	}
+	async testLocation({ config }) {
+		const basePath = config["basePath"];
+		if (typeof basePath !== "string" || basePath.length === 0) return {
+			ok: false,
+			error: "config.basePath must be a non-empty string"
+		};
+		try {
+			const stat = await node_fs.promises.stat(basePath).catch(() => null);
+			if (stat) {
+				if (!stat.isDirectory()) return {
+					ok: false,
+					error: `Path "${basePath}" exists but is not a directory`
+				};
+				await node_fs.promises.access(basePath, node_fs.constants.W_OK);
+				return { ok: true };
+			}
+			await node_fs.promises.mkdir(basePath, { recursive: true });
+			return { ok: true };
+		} catch (err) {
+			return {
+				ok: false,
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+	}
+	async resolve({ location, relativePath }) {
+		return safeResolve(getBasePath(location), relativePath);
+	}
+	async write({ location, relativePath, data }) {
+		const filePath = safeResolve(getBasePath(location), relativePath);
+		await node_fs.promises.mkdir(node_path.dirname(filePath), { recursive: true });
+		await node_fs.promises.writeFile(filePath, data);
+	}
+	async read({ location, relativePath }) {
+		const filePath = safeResolve(getBasePath(location), relativePath);
+		const buf = await node_fs.promises.readFile(filePath);
+		const out = new Uint8Array(new ArrayBuffer(buf.byteLength));
+		out.set(buf);
+		return out;
+	}
+	async exists({ location, relativePath }) {
+		const filePath = safeResolve(getBasePath(location), relativePath);
+		try {
+			await node_fs.promises.access(filePath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async list({ location, prefix }) {
+		const base = getBasePath(location);
+		const dir = prefix ? safeResolve(base, prefix) : node_path.resolve(base);
+		try {
+			return (await node_fs.promises.readdir(dir, { withFileTypes: true })).map((e) => prefix ? `${prefix}/${e.name}` : e.name);
+		} catch {
+			return [];
+		}
+	}
+	async delete({ location, relativePath }) {
+		const filePath = safeResolve(getBasePath(location), relativePath);
+		await node_fs.promises.rm(filePath, { force: true });
+	}
+	async getAvailableSpace({ location }) {
+		const base = node_path.resolve(getBasePath(location));
+		try {
+			let target = base;
+			while (!node_fs.existsSync(target)) {
+				const parent = node_path.dirname(target);
+				if (!parent || parent === target) return null;
+				target = parent;
+			}
+			const stats = await node_fs.promises.statfs(target);
+			return stats.bavail * stats.bsize;
+		} catch {
+			return null;
+		}
+	}
+	async beginUpload({ location, relativePath }) {
+		const target = safeResolve(getBasePath(location), relativePath);
+		const partial = `${target}.partial`;
+		await node_fs.promises.mkdir(node_path.dirname(target), { recursive: true });
+		await node_fs.promises.unlink(partial).catch(() => {});
+		const stream = node_fs.createWriteStream(partial);
+		const uploadId = (0, node_crypto.randomUUID)();
+		const session = {
+			stream,
+			target,
+			partial,
+			bytesWritten: 0,
+			timer: setTimeout(() => {
+				this.abortUpload({ uploadId }).catch(() => {});
+			}, SESSION_IDLE_TTL_MS)
+		};
+		this.uploads.set(uploadId, session);
+		return { uploadId };
+	}
+	async writeChunk({ uploadId, offset, data }) {
+		const session = this.uploads.get(uploadId);
+		if (!session) throw new Error(`filesystem-storage: upload session "${uploadId}" not found`);
+		if (offset !== session.bytesWritten) throw new Error(`filesystem-storage: chunk offset mismatch (expected ${session.bytesWritten}, got ${offset})`);
+		await new Promise((resolve, reject) => {
+			session.stream.write(data, (err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+		});
+		clearTimeout(session.timer);
+		const nextBytesWritten = session.bytesWritten + data.length;
+		this.uploads.set(uploadId, {
+			...session,
+			bytesWritten: nextBytesWritten,
+			timer: setTimeout(() => {
+				this.abortUpload({ uploadId }).catch(() => {});
+			}, SESSION_IDLE_TTL_MS)
+		});
+	}
+	async finalizeUpload({ uploadId }) {
+		const session = this.uploads.get(uploadId);
+		if (!session) throw new Error(`filesystem-storage: upload session "${uploadId}" not found`);
+		await new Promise((resolve, reject) => {
+			session.stream.end(() => resolve());
+			session.stream.on("error", reject);
+		});
+		await node_fs.promises.rename(session.partial, session.target);
+		clearTimeout(session.timer);
+		this.uploads.delete(uploadId);
+	}
+	async abortUpload({ uploadId }) {
+		const session = this.uploads.get(uploadId);
+		if (!session) return;
+		try {
+			session.stream.destroy();
+		} catch {}
+		await node_fs.promises.unlink(session.partial).catch(() => {});
+		clearTimeout(session.timer);
+		this.uploads.delete(uploadId);
+	}
+	async beginDownload({ location, relativePath }) {
+		const target = safeResolve(getBasePath(location), relativePath);
+		const stat = await node_fs.promises.stat(target);
+		const fd = await node_fs.promises.open(target, "r");
+		const downloadId = (0, node_crypto.randomUUID)();
+		const session = {
+			fd,
+			sizeBytes: stat.size,
+			timer: setTimeout(() => {
+				this.endDownload({ downloadId }).catch(() => {});
+			}, SESSION_IDLE_TTL_MS)
+		};
+		this.downloads.set(downloadId, session);
+		return {
+			downloadId,
+			sizeBytes: stat.size
+		};
+	}
+	async readChunk({ downloadId, offset, length }) {
+		const session = this.downloads.get(downloadId);
+		if (!session) throw new Error(`filesystem-storage: download session "${downloadId}" not found`);
+		const out = new Uint8Array(new ArrayBuffer(length));
+		const { bytesRead } = await session.fd.read(out, 0, length, offset);
+		clearTimeout(session.timer);
+		this.downloads.set(downloadId, {
+			...session,
+			timer: setTimeout(() => {
+				this.endDownload({ downloadId }).catch(() => {});
+			}, SESSION_IDLE_TTL_MS)
+		});
+		return out.subarray(0, bytesRead);
+	}
+	async endDownload({ downloadId }) {
+		const session = this.downloads.get(downloadId);
+		if (!session) return;
+		try {
+			await session.fd.close();
+		} catch {}
+		clearTimeout(session.timer);
+		this.downloads.delete(downloadId);
+	}
+	/**
+	* Abort all outstanding sessions. Called on addon shutdown so timers
+	* don't leak across hot-reload cycles.
+	*/
+	async dispose() {
+		const uploadIds = [...this.uploads.keys()];
+		const downloadIds = [...this.downloads.keys()];
+		await Promise.all(uploadIds.map((uploadId) => this.abortUpload({ uploadId })));
+		await Promise.all(downloadIds.map((downloadId) => this.endDownload({ downloadId })));
+	}
+};
+//#endregion
+//#region src/builtins/sqlite-storage/path-guard.ts
+/**
+* Allowed-root containment guard for the filesystem-browse cap. Pure +
+* synchronous so it is trivially unit-testable; the provider applies it AFTER
+* resolving the real path (so symlink escapes are also caught upstream).
+*/
+/** True iff `candidate` is one of, or nested under, an allowed root. */
+function isWithinAllowedRoots(candidate, allowedRoots) {
+	const norm = (0, node_path.resolve)(candidate);
+	return allowedRoots.some((root) => {
+		const r = (0, node_path.resolve)(root);
+		return norm === r || norm.startsWith(r.endsWith(node_path.sep) ? r : r + node_path.sep);
+	});
+}
+/** Throws unless `candidate` is within an allowed root. */
+function assertWithinAllowedRoots(candidate, allowedRoots) {
+	if (!isWithinAllowedRoots(candidate, allowedRoots)) throw new Error(`path "${candidate}" is not within an allowed root`);
+}
+//#endregion
+//#region src/builtins/sqlite-storage/filesystem-browse-provider.ts
+/**
+* Per-node filesystem-browse provider. Lists/creates directories under
+* operator-configured allowed roots only (sandboxed by `path-guard`). Backs the
+* `filesystem-browse` cap so the admin UI can pick a node + path for a
+* node-local storage location.
+*/
+var FilesystemBrowseProvider = class {
+	allowedRoots;
+	/** allowedRoots is injected (read from addon config) so it stays per-node + testable. */
+	constructor(allowedRoots) {
+		this.allowedRoots = allowedRoots;
+	}
+	async listAllowedRoots() {
+		return [...this.allowedRoots()];
+	}
+	async browse({ path }) {
+		const real = await (0, node_fs_promises.realpath)(path).catch(() => path);
+		assertWithinAllowedRoots(real, await this.resolvedRoots());
+		const entries = (await (0, node_fs_promises.readdir)(real, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => ({
+			name: d.name,
+			path: (0, node_path.join)(real, d.name)
+		}));
+		const fs = await (0, node_fs_promises.statfs)(real);
+		const totalBytes = fs.blocks * fs.bsize;
+		return {
+			path: real,
+			entries,
+			freeBytes: fs.bavail * fs.bsize,
+			totalBytes
+		};
+	}
+	async createDir({ path }) {
+		const parent = (0, node_path.dirname)(path);
+		assertWithinAllowedRoots((0, node_path.join)(await (0, node_fs_promises.realpath)(parent).catch(() => parent), (0, node_path.basename)(path)), await this.resolvedRoots());
+		await (0, node_fs_promises.mkdir)(path, { recursive: true });
+		return { path };
+	}
+	/** Allowed roots with symlinks resolved (falls back to the raw root if it does not exist). */
+	async resolvedRoots() {
+		return Promise.all(this.allowedRoots().map((r) => (0, node_fs_promises.realpath)(r).catch(() => r)));
+	}
+};
+//#endregion
+//#region src/builtins/sqlite-storage/filesystem-storage.addon.ts
+function defaultAllowedRoots() {
+	return [
+		"/mnt",
+		"/Volumes",
+		"/media",
+		(0, node_os.homedir)()
+	];
+}
+/**
+* Filesystem Storage addon — registers a filesystem-backed
+* `storage-provider` (Task 7).
+*
+* Pre-Task 7 this addon registered against the (then-collection)
+* `storage` cap. After Tasks 2/3/4 the consumer-facing `storage` cap is
+* a singleton owned by `storage-orchestrator`; the orchestrator
+* dispatches each call to whichever `storage-provider` matches
+* `location.providerId`.
+*
+* The OLD `rootPath` config field is preserved for back-compat: the
+* orchestrator's first-boot seeding step still uses the same env-var
+* resolution chain (operator override → `CAMSTACK_DATA` → fallback) to
+* derive the base path of every default location, then writes
+* `config.basePath` into each persisted `StorageLocation` row. The
+* provider itself is now stateless — every call carries the live
+* `StorageLocation` inline.
+*/
+var FilesystemStorageAddon = class extends _camstack_types.BaseAddon {
+	provider = null;
+	constructor() {
+		super({
+			rootPath: "camstack-data",
+			storageAllowedRoots: defaultAllowedRoots()
+		});
+	}
+	async onInitialize() {
+		this.provider = new FilesystemStorageProvider();
+		const browse = new FilesystemBrowseProvider(() => this.config.storageAllowedRoots);
+		this.ctx.logger.info("Filesystem storage-provider initialized");
+		return [{
+			capability: _camstack_types.storageProviderCapability,
+			provider: this.provider
+		}, {
+			capability: _camstack_types.filesystemBrowseCapability,
+			provider: browse
+		}];
+	}
+	async onShutdown() {
+		await this.provider?.dispose();
+		this.provider = null;
+	}
+	getProvider() {
+		return this.provider;
+	}
+};
+//#endregion
+exports.FilesystemStorageAddon = FilesystemStorageAddon;
+exports.default = FilesystemStorageAddon;
+exports.FilesystemStorageProvider = FilesystemStorageProvider;