@caryhu/codemine-forge 0.0.1-alpha.0

package/dist/virtual-file-system/storage.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createIndexedDbForgeStorage = exports.IndexedDbForgeStorage = exports.FORGE_INDEXED_DB_STORES = exports.FORGE_INDEXED_DB_VERSION = exports.FORGE_INDEXED_DB_NAME = void 0;
+const diagnostics_1 = require("./diagnostics");
+const errors_1 = require("./errors");
+const limits_1 = require("./limits");
+exports.FORGE_INDEXED_DB_NAME = "codemine-forge";
+exports.FORGE_INDEXED_DB_VERSION = 1;
+exports.FORGE_INDEXED_DB_STORES = {
+    buildCache: "build-cache",
+    packageCache: "package-cache",
+    workspaceFiles: "workspace-files",
+    workspaceMetadata: "workspace-metadata",
+    workspaceSnapshots: "workspace-snapshots",
+};
+class IndexedDbForgeStorage {
+    constructor(options = {}) {
+        this.databaseName = options.databaseName ?? exports.FORGE_INDEXED_DB_NAME;
+        this.limits = (0, limits_1.resolveForgeVirtualFileSystemLimits)(options.limits);
+    }
+    async loadWorkspace(workspaceId) {
+        const database = await this.openDatabase();
+        const transaction = database.transaction([
+            exports.FORGE_INDEXED_DB_STORES.workspaceMetadata,
+            exports.FORGE_INDEXED_DB_STORES.workspaceFiles,
+        ], "readonly");
+        const metadataStore = transaction.objectStore(exports.FORGE_INDEXED_DB_STORES.workspaceMetadata);
+        const fileStore = transaction.objectStore(exports.FORGE_INDEXED_DB_STORES.workspaceFiles);
+        const metadata = await requestToPromise(metadataStore.get(workspaceId));
+        if (metadata === undefined) {
+            await transactionDone(transaction);
+            return undefined;
+        }
+        const files = await Promise.all(metadata.filePaths.map(async (path) => {
+            const fileRecord = await requestToPromise(fileStore.get([workspaceId, path]));
+            return fileRecord?.file;
+        }));
+        await transactionDone(transaction);
+        return {
+            id: metadata.id,
+            name: metadata.name,
+            files: files.filter((file) => file !== undefined),
+            metadata: {
+                createdAt: metadata.createdAt,
+                updatedAt: metadata.updatedAt,
+            },
+            lock: metadata.lock,
+        };
+    }
+    async saveWorkspace(workspace) {
+        const database = await this.openDatabase();
+        const transaction = database.transaction([
+            exports.FORGE_INDEXED_DB_STORES.workspaceMetadata,
+            exports.FORGE_INDEXED_DB_STORES.workspaceFiles,
+        ], "readwrite");
+        const metadataStore = transaction.objectStore(exports.FORGE_INDEXED_DB_STORES.workspaceMetadata);
+        const fileStore = transaction.objectStore(exports.FORGE_INDEXED_DB_STORES.workspaceFiles);
+        metadataStore.put({
+            id: workspace.id,
+            name: workspace.name,
+            filePaths: workspace.files.map((file) => file.path),
+            createdAt: workspace.metadata.createdAt,
+            updatedAt: workspace.metadata.updatedAt,
+            lock: workspace.lock,
+        });
+        for (const file of workspace.files) {
+            fileStore.put({
+                workspaceId: workspace.id,
+                path: file.path,
+                file,
+            });
+        }
+        await transactionDone(transaction);
+    }
+    async getPackageCacheRecord(key) {
+        return this.getCacheRecord(exports.FORGE_INDEXED_DB_STORES.packageCache, key);
+    }
+    async putPackageCacheRecord(record) {
+        await this.putCacheRecord(exports.FORGE_INDEXED_DB_STORES.packageCache, record);
+    }
+    async getBuildCacheRecord(key) {
+        return this.getCacheRecord(exports.FORGE_INDEXED_DB_STORES.buildCache, key);
+    }
+    async putBuildCacheRecord(record) {
+        await this.putCacheRecord(exports.FORGE_INDEXED_DB_STORES.buildCache, record);
+    }
+    async clearBuildCache() {
+        const database = await this.openDatabase();
+        const transaction = database.transaction([exports.FORGE_INDEXED_DB_STORES.buildCache], "readwrite");
+        transaction
+            .objectStore(exports.FORGE_INDEXED_DB_STORES.buildCache)
+            .clear();
+        await transactionDone(transaction);
+    }
+    async getCacheRecord(storeName, key) {
+        const database = await this.openDatabase();
+        const transaction = database.transaction([storeName], "readonly");
+        const record = await requestToPromise(transaction.objectStore(storeName).get(key));
+        await transactionDone(transaction);
+        return record;
+    }
+    async putCacheRecord(storeName, record) {
+        await this.assertCacheLimit(storeName, record);
+        const database = await this.openDatabase();
+        const transaction = database.transaction([storeName], "readwrite");
+        transaction.objectStore(storeName).put(record);
+        await transactionDone(transaction);
+    }
+    async assertCacheLimit(storeName, record) {
+        const limitName = storeName === exports.FORGE_INDEXED_DB_STORES.packageCache
+            ? "packageCacheSize"
+            : "buildCacheSize";
+        const maximum = storeName === exports.FORGE_INDEXED_DB_STORES.packageCache
+            ? this.limits.maxPackageCacheSizeBytes
+            : this.limits.maxBuildCacheSizeBytes;
+        const database = await this.openDatabase();
+        const transaction = database.transaction([storeName], "readonly");
+        const existingRecords = await requestToPromise(transaction.objectStore(storeName).getAll());
+        await transactionDone(transaction);
+        const existingSize = existingRecords
+            .filter((existingRecord) => existingRecord.key !== record.key)
+            .reduce((total, existingRecord) => total + existingRecord.size, 0);
+        const actual = existingSize + record.size;
+        if (actual > maximum) {
+            throw new errors_1.ForgeFileSystemError((0, limits_1.createLimitExceededDiagnostic)(limitName, actual, maximum));
+        }
+    }
+    openDatabase() {
+        if (this.databasePromise !== undefined) {
+            return this.databasePromise;
+        }
+        if (!isIndexedDbAvailable()) {
+            return Promise.reject(new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "storage_unavailable",
+                message: "IndexedDB is not available in this environment.",
+            })));
+        }
+        this.databasePromise = new Promise((resolve, reject) => {
+            const request = indexedDB.open(this.databaseName, exports.FORGE_INDEXED_DB_VERSION);
+            request.onerror = () => reject(request.error);
+            request.onupgradeneeded = () => ensureStores(request.result);
+            request.onsuccess = () => resolve(request.result);
+        });
+        return this.databasePromise;
+    }
+}
+exports.IndexedDbForgeStorage = IndexedDbForgeStorage;
+function createIndexedDbForgeStorage(options) {
+    return new IndexedDbForgeStorage(options);
+}
+exports.createIndexedDbForgeStorage = createIndexedDbForgeStorage;
+function ensureStores(database) {
+    if (!database.objectStoreNames.contains(exports.FORGE_INDEXED_DB_STORES.workspaceMetadata)) {
+        database.createObjectStore(exports.FORGE_INDEXED_DB_STORES.workspaceMetadata, {
+            keyPath: "id",
+        });
+    }
+    if (!database.objectStoreNames.contains(exports.FORGE_INDEXED_DB_STORES.workspaceFiles)) {
+        database.createObjectStore(exports.FORGE_INDEXED_DB_STORES.workspaceFiles, {
+            keyPath: ["workspaceId", "path"],
+        });
+    }
+    if (!database.objectStoreNames.contains(exports.FORGE_INDEXED_DB_STORES.workspaceSnapshots)) {
+        database.createObjectStore(exports.FORGE_INDEXED_DB_STORES.workspaceSnapshots, {
+            keyPath: "id",
+        });
+    }
+    if (!database.objectStoreNames.contains(exports.FORGE_INDEXED_DB_STORES.packageCache)) {
+        database.createObjectStore(exports.FORGE_INDEXED_DB_STORES.packageCache, {
+            keyPath: "key",
+        });
+    }
+    if (!database.objectStoreNames.contains(exports.FORGE_INDEXED_DB_STORES.buildCache)) {
+        database.createObjectStore(exports.FORGE_INDEXED_DB_STORES.buildCache, {
+            keyPath: "key",
+        });
+    }
+}
+function requestToPromise(request) {
+    return new Promise((resolve, reject) => {
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result);
+    });
+}
+function transactionDone(transaction) {
+    return new Promise((resolve, reject) => {
+        transaction.onabort = () => reject(transaction.error);
+        transaction.onerror = () => reject(transaction.error);
+        transaction.oncomplete = () => resolve();
+    });
+}
+function isIndexedDbAvailable() {
+    return typeof indexedDB !== "undefined";
+}

package/dist/virtual-file-system/types.d.ts

@@ -0,0 +1,165 @@
+export type ForgeFileKind = "file" | "directory";
+export type ForgeFileSource = "user" | "template" | "generated" | "cache";
+export interface ForgeWorkspace {
+    readonly id: string;
+    readonly name: string;
+    readonly rootPath: "/";
+    readonly files: readonly ForgeFileRecord[];
+    readonly metadata?: ForgeWorkspaceMetadata;
+    readonly lock?: unknown;
+}
+export interface ForgeWorkspaceMetadata {
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface ForgeFileRecord {
+    readonly path: string;
+    readonly kind: ForgeFileKind;
+    readonly content?: Uint8Array;
+    readonly contentType?: string;
+    readonly contentHash?: string;
+    readonly size: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly source: ForgeFileSource;
+}
+export interface ForgeDirEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly kind: ForgeFileKind;
+    readonly stat: ForgeFileStat;
+}
+export interface ForgeFileStat {
+    readonly path: string;
+    readonly kind: ForgeFileKind;
+    readonly contentType?: string;
+    readonly contentHash?: string;
+    readonly size: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly source: ForgeFileSource;
+}
+export interface ForgeSnapshot {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly createdAt: string;
+    readonly files: readonly ForgeFileRecord[];
+    readonly lock?: unknown;
+    readonly metadata?: Record<string, unknown>;
+}
+export type ForgeDiagnosticSeverity = "info" | "warning" | "error";
+export type ForgeDiagnosticCode = "already_exists" | "directory_not_empty" | "invalid_path" | "is_directory" | "limit_exceeded" | "missing_parent" | "not_directory" | "not_file" | "not_found" | "not_implemented" | "path_traversal" | "storage_unavailable";
+export interface ForgeDiagnostic {
+    readonly code: ForgeDiagnosticCode;
+    readonly severity: ForgeDiagnosticSeverity;
+    readonly message: string;
+    readonly path?: string;
+    readonly relatedPath?: string;
+    readonly limit?: ForgeLimitDiagnostic;
+    readonly cause?: unknown;
+}
+export interface ForgeLimitDiagnostic {
+    readonly name: "buildCacheSize" | "fileCount" | "fileSize" | "packageCacheSize" | "workspaceSize";
+    readonly actual: number;
+    readonly maximum: number;
+}
+export type ForgeFileEvent = ForgeFileCreatedEvent | ForgeFileUpdatedEvent | ForgeFileDeletedEvent | ForgeFileRenamedEvent;
+export interface ForgeFileCreatedEvent {
+    readonly type: "file:created";
+    readonly path: string;
+    readonly stat: ForgeFileStat;
+}
+export interface ForgeFileUpdatedEvent {
+    readonly type: "file:updated";
+    readonly path: string;
+    readonly stat: ForgeFileStat;
+    readonly previousHash?: string;
+}
+export interface ForgeFileDeletedEvent {
+    readonly type: "file:deleted";
+    readonly path: string;
+    readonly stat?: ForgeFileStat;
+}
+export interface ForgeFileRenamedEvent {
+    readonly type: "file:renamed";
+    readonly from: string;
+    readonly to: string;
+    readonly stat: ForgeFileStat;
+}
+export type ForgeFileWatchListener = (event: ForgeFileEvent) => void;
+export type ForgeUnsubscribe = () => void;
+export interface ForgeWriteFileOptions {
+    readonly contentType?: string;
+    readonly source?: ForgeFileSource;
+}
+export interface ForgeDeleteOptions {
+    readonly recursive?: boolean;
+}
+export interface ForgeMkdirOptions {
+    readonly recursive?: boolean;
+    readonly source?: ForgeFileSource;
+}
+export interface ForgeSnapshotOptions {
+    readonly includeGeneratedFiles?: boolean;
+    readonly includeRuntimeMetadata?: boolean;
+}
+export interface ForgeRestoreOptions {
+    readonly preserveWorkspaceId?: boolean;
+}
+export interface ForgeVirtualFileSystemOptions {
+    readonly workspaceId?: string;
+    readonly workspaceName?: string;
+    readonly files?: readonly ForgeFileRecord[];
+    readonly metadata?: ForgeWorkspaceMetadata;
+    readonly lock?: unknown;
+    readonly storage?: ForgeVirtualFileSystemStorage;
+    readonly limits?: ForgeVirtualFileSystemLimits;
+}
+export interface ForgeOpenVirtualFileSystemOptions {
+    readonly workspaceId: string;
+    readonly workspaceName?: string;
+    readonly storage?: ForgeVirtualFileSystemStorage;
+    readonly limits?: ForgeVirtualFileSystemLimits;
+}
+export interface ForgeVirtualFileSystemStorage {
+    loadWorkspace(workspaceId: string): Promise<ForgePersistedWorkspace | undefined>;
+    saveWorkspace(workspace: ForgePersistedWorkspace): Promise<void>;
+    getPackageCacheRecord(key: string): Promise<ForgePackageCacheRecord | undefined>;
+    putPackageCacheRecord(record: ForgePackageCacheRecord): Promise<void>;
+    getBuildCacheRecord(key: string): Promise<ForgeBuildCacheRecord | undefined>;
+    putBuildCacheRecord(record: ForgeBuildCacheRecord): Promise<void>;
+    clearBuildCache(): Promise<void>;
+}
+export interface ForgePersistedWorkspace {
+    readonly id: string;
+    readonly name: string;
+    readonly files: readonly ForgeFileRecord[];
+    readonly metadata: ForgeWorkspaceMetadata;
+    readonly lock?: unknown;
+}
+export interface ForgePackageCacheRecord {
+    readonly key: string;
+    readonly value: unknown;
+    readonly size: number;
+    readonly updatedAt: string;
+}
+export interface ForgeBuildCacheRecord {
+    readonly key: string;
+    readonly value: unknown;
+    readonly size: number;
+    readonly updatedAt: string;
+}
+export interface ForgeVirtualFileSystemLimits {
+    readonly maxFileSizeBytes?: number;
+    readonly maxWorkspaceSizeBytes?: number;
+    readonly maxFileCount?: number;
+    readonly maxPackageCacheSizeBytes?: number;
+    readonly maxBuildCacheSizeBytes?: number;
+}
+export interface ResolvedForgeVirtualFileSystemLimits {
+    readonly maxFileSizeBytes: number;
+    readonly maxWorkspaceSizeBytes: number;
+    readonly maxFileCount: number;
+    readonly maxPackageCacheSizeBytes: number;
+    readonly maxBuildCacheSizeBytes: number;
+}

package/dist/virtual-file-system/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@caryhu/codemine-forge",
+  "version": "0.0.1-alpha.0",
+  "description": "Browser-side runtime layer for Codemine demos.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "esbuild-wasm": "^0.28.1",
+    "typescript": "4.9.5"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "^6.2.5",
+    "playwright": "^1.61.1"
+  },
+  "scripts": {
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "demo": "pnpm run test:build && node demo/terminal-demo.mjs",
+    "demo:web": "pnpm run test:build && node demo/web-demo-server.mjs",
+    "demo:static": "node demo/generate-static-demo.mjs",
+    "publish:npm": "node scripts/publish-npm.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:build": "tsc -p tsconfig.test.json",
+    "test": "pnpm run test:build && node test/virtual-file-system.test.mjs && node test/indexeddb-workspace-restore.test.mjs && node test/react-vite-template-dev-loop.test.mjs && node test/react-vite-template-diagnostics.test.mjs && node test/package-resolution.test.mjs && node test/build-pipeline.test.mjs && node test/dev-server-preview.test.mjs && node test/terminal-commands.test.mjs && node test/esbuild-wasm-worker.test.mjs && node test/browser-preview-execution.test.mjs && node test/demo-samples.test.mjs",
+    "test:browser-preview": "pnpm run test:build && node test/browser-preview-execution.test.mjs",
+    "test:demo-samples": "pnpm run test:build && node test/demo-samples.test.mjs",
+    "test:static-demo": "node test/static-demo.test.mjs",
+    "validate": "pnpm run typecheck && pnpm test"
+  }
+}