@camstack/core 0.1.15 → 0.1.17

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

@@ -1,9 +1,307 @@
-import {
-  FilesystemStorageAddon,
-  filesystem_storage_addon_default
-} from "../../chunk-UJI4LN5P.mjs";
-export {
-  FilesystemStorageAddon,
-  filesystem_storage_addon_default as default
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { BaseAddon, STORAGE_LOCATION_TYPES, storageProviderCapability } from "@camstack/types";
+//#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 = path.resolve(base);
+	const target = path.resolve(normalizedBase, relativePath);
+	if (target !== normalizedBase && !target.startsWith(normalizedBase + 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,
+			supportedLocationTypes: STORAGE_LOCATION_TYPES,
+			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 fs.promises.stat(basePath).catch(() => null);
+			if (stat) {
+				if (!stat.isDirectory()) return {
+					ok: false,
+					error: `Path "${basePath}" exists but is not a directory`
+				};
+				await fs.promises.access(basePath, fs.constants.W_OK);
+				return { ok: true };
+			}
+			await 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 fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+		await fs.promises.writeFile(filePath, data);
+	}
+	async read({ location, relativePath }) {
+		const filePath = safeResolve(getBasePath(location), relativePath);
+		const buf = await 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 fs.promises.access(filePath);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	async list({ location, prefix }) {
+		const base = getBasePath(location);
+		const dir = prefix ? safeResolve(base, prefix) : path.resolve(base);
+		try {
+			return (await 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 fs.promises.rm(filePath, { force: true });
+	}
+	async getAvailableSpace({ location }) {
+		const base = path.resolve(getBasePath(location));
+		try {
+			let target = base;
+			while (!fs.existsSync(target)) {
+				const parent = path.dirname(target);
+				if (!parent || parent === target) return null;
+				target = parent;
+			}
+			const stats = await 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 fs.promises.mkdir(path.dirname(target), { recursive: true });
+		await fs.promises.unlink(partial).catch(() => {});
+		const stream = fs.createWriteStream(partial);
+		const uploadId = 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 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 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 fs.promises.stat(target);
+		const fd = await fs.promises.open(target, "r");
+		const downloadId = 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/filesystem-storage.addon.ts
+/**
+* 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 BaseAddon {
+	provider = null;
+	constructor() {
+		super({ rootPath: "camstack-data" });
+	}
+	async onInitialize() {
+		this.provider = new FilesystemStorageProvider();
+		this.ctx.logger.info("Filesystem storage-provider initialized");
+		return [{
+			capability: storageProviderCapability,
+			provider: this.provider
+		}];
+	}
+	async onShutdown() {
+		await this.provider?.dispose();
+		this.provider = null;
+	}
+	getProvider() {
+		return this.provider;
+	}
+};
+//#endregion
+export { FilesystemStorageAddon, FilesystemStorageAddon as default, FilesystemStorageProvider as t };
+
 //# sourceMappingURL=filesystem-storage.addon.mjs.map

package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"file":"filesystem-storage.addon.mjs","names":[],"sources":["../../../src/builtins/sqlite-storage/filesystem-storage-provider.ts","../../../src/builtins/sqlite-storage/filesystem-storage.addon.ts"],"sourcesContent":["/**\n * Filesystem `storage-provider` (Task 7).\n *\n * Implements the `storage-provider` collection cap. Replaces the legacy\n * sync `IStorageProvider` shape — every method now takes the live\n * `StorageLocation` inline (no per-provider location state) and works\n * off `location.config.basePath`.\n *\n * Adds chunked upload (`.partial` rename trick) + chunked download\n * sessions for moving multi-GB archives without buffering the whole\n * archive in memory. Sessions auto-expire after 5 minutes idle.\n *\n * The legacy `FilesystemStorageProvider` in `@camstack/types/node` is\n * deliberately untouched — it still backs the sync `ctx.kernel.storage`\n * helper that addons like `pipeline-analytics` use to derive paths\n * synchronously. That sync API will be retired in a later refactor;\n * Task 7 is scoped to the cap surface only.\n */\nimport * as fs from 'node:fs'\nimport * as path from 'node:path'\nimport { randomUUID } from 'node:crypto'\nimport type { FileHandle } from 'node:fs/promises'\nimport type {\n  IStorageProviderImpl,\n  StorageLocation,\n  StorageLocationType,\n} from '@camstack/types'\nimport { STORAGE_LOCATION_TYPES } from '@camstack/types'\n\n/** Idle TTL for upload + download sessions. */\nconst SESSION_IDLE_TTL_MS = 5 * 60 * 1000\n\ninterface UploadSession {\n  readonly stream: fs.WriteStream\n  readonly target: string\n  readonly partial: string\n  bytesWritten: number\n  timer: NodeJS.Timeout\n}\n\ninterface DownloadSession {\n  readonly fd: FileHandle\n  readonly sizeBytes: number\n  timer: NodeJS.Timeout\n}\n\n/**\n * Resolve `location.config.basePath` into a string. Throws an actionable\n * error when the field is missing or wrong-typed — every primitive\n * funnels through here, so a missing field surfaces as a single clear\n * message instead of a downstream `path.join` TypeError.\n */\nfunction getBasePath(location: StorageLocation): string {\n  const cfg = location.config as Record<string, unknown>\n  const basePath = cfg['basePath']\n  if (typeof basePath !== 'string' || basePath.length === 0) {\n    throw new Error(\n      `filesystem-storage: location \"${location.id}\" missing string config.basePath`,\n    )\n  }\n  return basePath\n}\n\n/**\n * Resolve a relative path against the location's base, rejecting any\n * traversal that escapes the base directory. Mirrors the\n * `addon-asset` endpoint security check in `main.ts`: normalize both\n * the base + the joined target, then enforce `target.startsWith(base + sep)`\n * (with the `+ sep` guard so `/data` doesn't accidentally allow\n * `/datasecret`).\n */\nfunction safeResolve(base: string, relativePath: string): string {\n  const normalizedBase = path.resolve(base)\n  const target = path.resolve(normalizedBase, relativePath)\n  if (target !== normalizedBase && !target.startsWith(normalizedBase + path.sep)) {\n    throw new Error(\n      `filesystem-storage: relativePath \"${relativePath}\" escapes basePath \"${normalizedBase}\"`,\n    )\n  }\n  return target\n}\n\nexport class FilesystemStorageProvider implements IStorageProviderImpl {\n  static readonly providerId = 'filesystem-storage'\n  static readonly displayName = 'Filesystem'\n\n  private readonly uploads = new Map<string, UploadSession>()\n  private readonly downloads = new Map<string, DownloadSession>()\n\n  // ── Self-description ────────────────────────────────────────────────\n\n  async getProviderInfo(): Promise<{\n    readonly providerId: string\n    readonly displayName: string\n    readonly supportedLocationTypes: readonly StorageLocationType[]\n    readonly configSchema: unknown\n  }> {\n    return {\n      providerId: FilesystemStorageProvider.providerId,\n      displayName: FilesystemStorageProvider.displayName,\n      // Filesystem can host every location type — the orchestrator's\n      // first-boot seeding walks this list to provision defaults.\n      supportedLocationTypes: STORAGE_LOCATION_TYPES,\n      // Minimal schema — the only required field is `basePath`. Casted\n      // through `unknown` because the cap surface declares\n      // `configSchema: z.unknown()` (the admin UI casts back at the\n      // consumption site to `ConfigUISchemaWithValues`).\n      configSchema: {\n        sections: [\n          {\n            id: 'filesystem-storage',\n            title: 'Filesystem',\n            fields: [\n              {\n                type: 'text',\n                key: 'basePath',\n                label: 'Base path',\n                description: 'Absolute directory path where files are stored.',\n                required: true,\n              },\n            ],\n          },\n        ],\n      },\n    }\n  }\n\n  async testLocation({ config }: { readonly config: Record<string, unknown> }): Promise<{\n    readonly ok: boolean\n    readonly error?: string\n  }> {\n    const basePath = config['basePath']\n    if (typeof basePath !== 'string' || basePath.length === 0) {\n      return { ok: false, error: 'config.basePath must be a non-empty string' }\n    }\n    try {\n      const stat = await fs.promises.stat(basePath).catch(() => null)\n      if (stat) {\n        if (!stat.isDirectory()) {\n          return { ok: false, error: `Path \"${basePath}\" exists but is not a directory` }\n        }\n        // Confirm we can write to it.\n        await fs.promises.access(basePath, fs.constants.W_OK)\n        return { ok: true }\n      }\n      // Doesn't exist — try to create it.\n      await fs.promises.mkdir(basePath, { recursive: true })\n      return { ok: true }\n    } catch (err) {\n      return {\n        ok: false,\n        error: err instanceof Error ? err.message : String(err),\n      }\n    }\n  }\n\n  // ── Small-file primitives ───────────────────────────────────────────\n\n  async resolve({\n    location,\n    relativePath,\n  }: {\n    readonly location: StorageLocation\n    readonly relativePath: string\n  }): Promise<string> {\n    return safeResolve(getBasePath(location), relativePath)\n  }\n\n  async write({\n    location,\n    relativePath,\n    data,\n  }: {\n    readonly location: StorageLocation\n    readonly relativePath: string\n    readonly data: Uint8Array\n  }): Promise<void> {\n    const filePath = safeResolve(getBasePath(location), relativePath)\n    await fs.promises.mkdir(path.dirname(filePath), { recursive: true })\n    await fs.promises.writeFile(filePath, data)\n  }\n\n  async read({\n    location,\n    relativePath,\n  }: {\n    readonly location: StorageLocation\n    readonly relativePath: string\n  }): Promise<Uint8Array<ArrayBuffer>> {\n    const filePath = safeResolve(getBasePath(location), relativePath)\n    const buf = await fs.promises.readFile(filePath)\n    // The cap surface narrows `Uint8Array` to `Uint8Array<ArrayBuffer>`\n    // (Node's `Buffer` types as `Uint8Array<ArrayBufferLike>` which can\n    // also wrap a `SharedArrayBuffer`). Copy through a fresh\n    // `ArrayBuffer` so the structural narrowing succeeds. The copy is\n    // cheap relative to the disk read; for chunked transfers callers\n    // should use `beginDownload`/`readChunk` which already allocates\n    // its own ArrayBuffer-backed Buffer.\n    const out = new Uint8Array(new ArrayBuffer(buf.byteLength))\n    out.set(buf)\n    return out\n  }\n\n  async exists({\n    location,\n    relativePath,\n  }: {\n    readonly location: StorageLocation\n    readonly relativePath: string\n  }): Promise<boolean> {\n    const filePath = safeResolve(getBasePath(location), relativePath)\n    try {\n      await fs.promises.access(filePath)\n      return true\n    } catch {\n      return false\n    }\n  }\n\n  async list({\n    location,\n    prefix,\n  }: {\n    readonly location: StorageLocation\n    readonly prefix?: string\n  }): Promise<readonly string[]> {\n    const base = getBasePath(location)\n    const dir = prefix ? safeResolve(base, prefix) : path.resolve(base)\n    try {\n      const entries = await fs.promises.readdir(dir, { withFileTypes: true })\n      // Return RELATIVE-to-location filenames so consumers can pass\n      // them straight back to `read({ location, relativePath })`.\n      return entries.map(e => (prefix ? `${prefix}/${e.name}` : e.name))\n    } catch {\n      return []\n    }\n  }\n\n  async delete({\n    location,\n    relativePath,\n  }: {\n    readonly location: StorageLocation\n    readonly relativePath: string\n  }): Promise<void> {\n    const filePath = safeResolve(getBasePath(location), relativePath)\n    await fs.promises.rm(filePath, { force: true })\n  }\n\n  async getAvailableSpace({\n    location,\n  }: {\n    readonly location: StorageLocation\n  }): Promise<number | null> {\n    const base = path.resolve(getBasePath(location))\n    // Walk up to the nearest existing ancestor when the directory\n    // hasn't been created yet (lazy-mkdir contract from the legacy\n    // provider) so statfs can still report mount-point free space.\n    try {\n      let target = base\n      while (!fs.existsSync(target)) {\n        const parent = path.dirname(target)\n        if (!parent || parent === target) return null\n        target = parent\n      }\n      const stats = await fs.promises.statfs(target)\n      return stats.bavail * stats.bsize\n    } catch {\n      return null\n    }\n  }\n\n  // ── Chunked upload ──────────────────────────────────────────────────\n\n  async beginUpload({\n    location,\n    relativePath,\n  }: {\n    readonly location: StorageLocation\n    readonly relativePath: string\n    readonly sizeBytes?: number\n  }): Promise<{ readonly uploadId: string }> {\n    const target = safeResolve(getBasePath(location), relativePath)\n    const partial = `${target}.partial`\n    await fs.promises.mkdir(path.dirname(target), { recursive: true })\n    // Wipe a stale `.partial` from a previous aborted run so the\n    // append-zero offset stays correct.\n    await fs.promises.unlink(partial).catch(() => {})\n    const stream = fs.createWriteStream(partial)\n    const uploadId = randomUUID()\n    const session: UploadSession = {\n      stream,\n      target,\n      partial,\n      bytesWritten: 0,\n      timer: setTimeout(() => {\n        void this.abortUpload({ uploadId }).catch(() => {})\n      }, SESSION_IDLE_TTL_MS),\n    }\n    this.uploads.set(uploadId, session)\n    return { uploadId }\n  }\n\n  async writeChunk({\n    uploadId,\n    offset,\n    data,\n  }: {\n    readonly uploadId: string\n    readonly offset: number\n    readonly data: Uint8Array\n  }): Promise<void> {\n    const session = this.uploads.get(uploadId)\n    if (!session) {\n      throw new Error(`filesystem-storage: upload session \"${uploadId}\" not found`)\n    }\n    if (offset !== session.bytesWritten) {\n      throw new Error(\n        `filesystem-storage: chunk offset mismatch (expected ${session.bytesWritten}, got ${offset})`,\n      )\n    }\n    await new Promise<void>((resolve, reject) => {\n      session.stream.write(data, err => {\n        if (err) reject(err)\n        else resolve()\n      })\n    })\n    // Replace session with updated bytesWritten + reset timer (immutable\n    // update; old timer cleared).\n    clearTimeout(session.timer)\n    const nextBytesWritten = session.bytesWritten + data.length\n    this.uploads.set(uploadId, {\n      ...session,\n      bytesWritten: nextBytesWritten,\n      timer: setTimeout(() => {\n        void this.abortUpload({ uploadId }).catch(() => {})\n      }, SESSION_IDLE_TTL_MS),\n    })\n  }\n\n  async finalizeUpload({ uploadId }: { readonly uploadId: string }): Promise<void> {\n    const session = this.uploads.get(uploadId)\n    if (!session) {\n      throw new Error(`filesystem-storage: upload session \"${uploadId}\" not found`)\n    }\n    await new Promise<void>((resolve, reject) => {\n      session.stream.end(() => resolve())\n      session.stream.on('error', reject)\n    })\n    await fs.promises.rename(session.partial, session.target)\n    clearTimeout(session.timer)\n    this.uploads.delete(uploadId)\n  }\n\n  async abortUpload({ uploadId }: { readonly uploadId: string }): Promise<void> {\n    const session = this.uploads.get(uploadId)\n    if (!session) return // Already cleaned up — idempotent.\n    try {\n      session.stream.destroy()\n    } catch {\n      // Best-effort.\n    }\n    await fs.promises.unlink(session.partial).catch(() => {})\n    clearTimeout(session.timer)\n    this.uploads.delete(uploadId)\n  }\n\n  // ── Chunked download ────────────────────────────────────────────────\n\n  async beginDownload({\n    location,\n    relativePath,\n  }: {\n    readonly location: StorageLocation\n    readonly relativePath: string\n  }): Promise<{ readonly downloadId: string; readonly sizeBytes: number }> {\n    const target = safeResolve(getBasePath(location), relativePath)\n    const stat = await fs.promises.stat(target)\n    const fd = await fs.promises.open(target, 'r')\n    const downloadId = randomUUID()\n    const session: DownloadSession = {\n      fd,\n      sizeBytes: stat.size,\n      timer: setTimeout(() => {\n        void this.endDownload({ downloadId }).catch(() => {})\n      }, SESSION_IDLE_TTL_MS),\n    }\n    this.downloads.set(downloadId, session)\n    return { downloadId, sizeBytes: stat.size }\n  }\n\n  async readChunk({\n    downloadId,\n    offset,\n    length,\n  }: {\n    readonly downloadId: string\n    readonly offset: number\n    readonly length: number\n  }): Promise<Uint8Array<ArrayBuffer>> {\n    const session = this.downloads.get(downloadId)\n    if (!session) {\n      throw new Error(`filesystem-storage: download session \"${downloadId}\" not found`)\n    }\n    // Allocate over an explicit `ArrayBuffer` so the narrowing required\n    // by the cap surface (`Uint8Array<ArrayBuffer>`) succeeds — `Buffer`\n    // types as `Uint8Array<ArrayBufferLike>` which TS won't widen\n    // through the structural check.\n    const out = new Uint8Array(new ArrayBuffer(length))\n    const { bytesRead } = await session.fd.read(out, 0, length, offset)\n    // Reset TTL on activity.\n    clearTimeout(session.timer)\n    this.downloads.set(downloadId, {\n      ...session,\n      timer: setTimeout(() => {\n        void this.endDownload({ downloadId }).catch(() => {})\n      }, SESSION_IDLE_TTL_MS),\n    })\n    return out.subarray(0, bytesRead)\n  }\n\n  async endDownload({ downloadId }: { readonly downloadId: string }): Promise<void> {\n    const session = this.downloads.get(downloadId)\n    if (!session) return\n    try {\n      await session.fd.close()\n    } catch {\n      // Best-effort.\n    }\n    clearTimeout(session.timer)\n    this.downloads.delete(downloadId)\n  }\n\n  /**\n   * Abort all outstanding sessions. Called on addon shutdown so timers\n   * don't leak across hot-reload cycles.\n   */\n  async dispose(): Promise<void> {\n    const uploadIds = [...this.uploads.keys()]\n    const downloadIds = [...this.downloads.keys()]\n    await Promise.all(uploadIds.map(uploadId => this.abortUpload({ uploadId })))\n    await Promise.all(downloadIds.map(downloadId => this.endDownload({ downloadId })))\n  }\n}\n\nexport default FilesystemStorageProvider\n","import type { ProviderRegistration } from '@camstack/types'\nimport { BaseAddon, storageProviderCapability } from '@camstack/types'\nimport { FilesystemStorageProvider } from './filesystem-storage-provider.js'\n\ninterface FilesystemStorageConfig {\n  readonly rootPath: string\n}\n\n/**\n * Filesystem Storage addon — registers a filesystem-backed\n * `storage-provider` (Task 7).\n *\n * Pre-Task 7 this addon registered against the (then-collection)\n * `storage` cap. After Tasks 2/3/4 the consumer-facing `storage` cap is\n * a singleton owned by `storage-orchestrator`; the orchestrator\n * dispatches each call to whichever `storage-provider` matches\n * `location.providerId`.\n *\n * The OLD `rootPath` config field is preserved for back-compat: the\n * orchestrator's first-boot seeding step still uses the same env-var\n * resolution chain (operator override → `CAMSTACK_DATA` → fallback) to\n * derive the base path of every default location, then writes\n * `config.basePath` into each persisted `StorageLocation` row. The\n * provider itself is now stateless — every call carries the live\n * `StorageLocation` inline.\n */\nexport class FilesystemStorageAddon extends BaseAddon<FilesystemStorageConfig> {\n  private provider: FilesystemStorageProvider | null = null\n\n  constructor() {\n    super({ rootPath: 'camstack-data' })\n  }\n\n  protected async onInitialize(): Promise<ProviderRegistration[]> {\n    this.provider = new FilesystemStorageProvider()\n    this.ctx.logger.info('Filesystem storage-provider initialized')\n    return [{ capability: storageProviderCapability, provider: this.provider }]\n  }\n\n  protected async onShutdown(): Promise<void> {\n    await this.provider?.dispose()\n    this.provider = null\n  }\n\n  getProvider(): FilesystemStorageProvider | null {\n    return this.provider\n  }\n}\n\nexport default FilesystemStorageAddon\n"],"mappings":"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"}

package/dist/builtins/sqlite-storage/index.d.ts

@@ -0,0 +1,12 @@
+export { FilesystemStorageProvider } from './filesystem-storage-provider.js';
+export { FilesystemStorageAddon } from './filesystem-storage.addon.js';
+export { SqliteSettingsBackend } from './sqlite-settings-backend.js';
+export { SqliteSettingsAddon } from './sqlite-settings.addon.js';
+export { SettingsStore } from './settings-store.js';
+export { CORE_TABLE_DDL, addonTableToDdl } from './sql-schema.js';
+export type { AddonTableSchema } from './sql-schema.js';
+export { DeviceStore } from './device-store.js';
+export type { DeviceRow } from './device-store.js';
+export { ConfigStore } from './config-store.js';
+export { FilesystemStorageAddon as default } from './filesystem-storage.addon.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/builtins/sqlite-storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builtins/sqlite-storage/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAA;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAG/C,OAAO,EAAE,sBAAsB,IAAI,OAAO,EAAE,MAAM,+BAA+B,CAAA"}