@caryhu/codemine-forge 0.0.1-alpha.0 → 0.0.1-alpha.2

package/dist/telemetry/index.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitForgeTelemetry = exports.createForgeUnsupportedPackageReason = exports.summarizeForgeTelemetryDiagnostics = exports.completeForgeTelemetryTiming = exports.startForgeTelemetryTiming = exports.TELEMETRY_CAPABILITY = void 0;
+exports.TELEMETRY_CAPABILITY = "telemetry";
+function startForgeTelemetryTiming(startedAt) {
+    return {
+        startedAt,
+        startedMs: Date.now(),
+    };
+}
+exports.startForgeTelemetryTiming = startForgeTelemetryTiming;
+function completeForgeTelemetryTiming(start, endedAt) {
+    return {
+        startedAt: start.startedAt,
+        endedAt,
+        durationMs: Math.max(0, Date.now() - start.startedMs),
+    };
+}
+exports.completeForgeTelemetryTiming = completeForgeTelemetryTiming;
+function summarizeForgeTelemetryDiagnostics(diagnostics) {
+    return diagnostics.map((diagnostic) => ({
+        code: diagnostic.code,
+        severity: diagnostic.severity,
+        message: diagnostic.message,
+        path: diagnostic.path,
+        dependencyName: diagnostic.dependencyName,
+        requestedRange: diagnostic.requestedRange,
+        importer: diagnostic.importer,
+        importSpecifier: diagnostic.importSpecifier,
+        limitName: diagnostic.limit?.name,
+    }));
+}
+exports.summarizeForgeTelemetryDiagnostics = summarizeForgeTelemetryDiagnostics;
+function createForgeUnsupportedPackageReason(diagnostic) {
+    if (!isUnsupportedPackageDiagnosticCode(diagnostic.code)) {
+        return undefined;
+    }
+    return {
+        code: diagnostic.code,
+        message: diagnostic.message,
+        dependencyName: diagnostic.dependencyName,
+        requestedRange: diagnostic.requestedRange,
+    };
+}
+exports.createForgeUnsupportedPackageReason = createForgeUnsupportedPackageReason;
+function emitForgeTelemetry(reporter, event) {
+    if (reporter === undefined) {
+        return;
+    }
+    try {
+        reporter(event);
+    }
+    catch {
+        // Telemetry is observational and must not alter runtime behavior.
+    }
+}
+exports.emitForgeTelemetry = emitForgeTelemetry;
+function isUnsupportedPackageDiagnosticCode(code) {
+    return [
+        "invalid_dependency",
+        "offline_cache_miss",
+        "unresolved_package",
+        "unsupported_range",
+    ].includes(code);
+}

package/dist/terminal-commands/npm-build.js

@@ -20,7 +20,9 @@ class NpmRunBuildCommandHandler {
                 diagnostics: [],
             };
         }
-        const buildResult = await context.buildPipeline.build();
+        const buildResult = await context.buildPipeline.build({
+            signal: context.signal,
+        });
         if (!buildResult.success) {
             const firstDiagnostic = buildResult.diagnostics[0];
             return {

package/dist/terminal-commands/npm-dev.js

@@ -20,7 +20,9 @@ class NpmRunDevCommandHandler {
                 diagnostics: [],
             };
         }
-        const startResult = await context.devServerPreview.start();
+        const startResult = await context.devServerPreview.start({
+            signal: context.signal,
+        });
         if (!startResult.success) {
             const firstDiagnostic = startResult.diagnostics[0];
             return {

package/dist/terminal-commands/npm-install.js

@@ -25,8 +25,8 @@ class NpmInstallCommandHandler {
             return {
                 command: context.command,
                 exitCode: 0,
-                output,
-                diagnostics: [],
+                output: [...output, ...warningOutput(packageResolution.warnings)],
+                diagnostics: packageResolution.warnings,
                 packageResolution,
             };
         }
@@ -54,3 +54,8 @@ function stdout(text) {
 function stderr(text) {
     return { kind: "stderr", text };
 }
+function warningOutput(diagnostics) {
+    return diagnostics
+        .filter((diagnostic) => diagnostic.severity === "warning")
+        .map((diagnostic) => stderr(`Forge warning: ${diagnostic.message}`));
+}

package/dist/terminal-commands/terminal.d.ts

@@ -7,6 +7,7 @@ export declare class DefaultForgeTerminal implements ForgeTerminal {
     constructor(options: ForgeTerminalOptions);
     execute(commandText: string, executeOptions?: {
         readonly cwd?: string;
+        readonly signal?: AbortSignal;
     }): Promise<ForgeCommandResult>;
 }
 export declare function createForgeTerminal(options: ForgeTerminalOptions): ForgeTerminal;

package/dist/terminal-commands/terminal.js

@@ -42,6 +42,7 @@ class DefaultForgeTerminal {
             buildPipeline: this.options.buildPipeline,
             devServerPreview: this.options.devServerPreview,
             packageResolver: this.options.packageResolver,
+            signal: executeOptions.signal,
         });
     }
 }

package/dist/terminal-commands/types.d.ts

@@ -35,6 +35,7 @@ export interface ForgeCommandContext {
     readonly buildPipeline?: ForgeBuildPipeline;
     readonly devServerPreview?: ForgeDevServerPreview;
     readonly packageResolver: ForgePackageResolver;
+    readonly signal?: AbortSignal;
 }
 export interface ForgeCommandHandler {
     readonly name: string;
@@ -44,6 +45,7 @@ export interface ForgeCommandHandler {
 }
 export interface ForgeTerminalExecuteOptions {
     readonly cwd?: string;
+    readonly signal?: AbortSignal;
 }
 export interface ForgeTerminalOptions {
     readonly buildPipeline?: ForgeBuildPipeline;

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

@@ -8,6 +8,7 @@ export interface ForgeDiagnosticInput {
 }
 export declare function createForgeDiagnostic(input: ForgeDiagnosticInput): ForgeDiagnostic;
 export declare function createInvalidPathDiagnostic(path: string, message?: string): ForgeDiagnostic;
+export declare function createInvalidSnapshotDiagnostic(message?: string, cause?: unknown): ForgeDiagnostic;
 export declare function createPathTraversalDiagnostic(path: string): ForgeDiagnostic;
 export declare function createNotFoundDiagnostic(path: string): ForgeDiagnostic;
 export declare function createMissingParentDiagnostic(path: string): ForgeDiagnostic;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createNotImplementedDiagnostic = exports.createMissingParentDiagnostic = exports.createNotFoundDiagnostic = exports.createPathTraversalDiagnostic = exports.createInvalidPathDiagnostic = exports.createForgeDiagnostic = void 0;
+exports.createNotImplementedDiagnostic = exports.createMissingParentDiagnostic = exports.createNotFoundDiagnostic = exports.createPathTraversalDiagnostic = exports.createInvalidSnapshotDiagnostic = exports.createInvalidPathDiagnostic = exports.createForgeDiagnostic = void 0;
 function createForgeDiagnostic(input) {
     return {
         code: input.code,
@@ -20,6 +20,14 @@ function createInvalidPathDiagnostic(path, message = "Path is invalid.") {
     });
 }
 exports.createInvalidPathDiagnostic = createInvalidPathDiagnostic;
+function createInvalidSnapshotDiagnostic(message = "Workspace snapshot payload is invalid.", cause) {
+    return createForgeDiagnostic({
+        code: "invalid_snapshot",
+        message,
+        cause,
+    });
+}
+exports.createInvalidSnapshotDiagnostic = createInvalidSnapshotDiagnostic;
 function createPathTraversalDiagnostic(path) {
     return createForgeDiagnostic({
         code: "path_traversal",

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

@@ -1,11 +1,13 @@
 import type { ForgeDeleteOptions, ForgeDirEntry, ForgeFileStat, ForgeFileWatchListener, ForgeMkdirOptions, ForgeOpenVirtualFileSystemOptions, ForgeRestoreOptions, ForgeSnapshot, ForgeSnapshotOptions, ForgeUnsubscribe, ForgeVirtualFileSystemOptions, ForgeWriteFileOptions } from "./types";
 export { DEFAULT_FORGE_VFS_LIMITS, createLimitExceededDiagnostic, resolveForgeVirtualFileSystemLimits, } from "./limits";
-export { createForgeDiagnostic, createInvalidPathDiagnostic, createMissingParentDiagnostic, createNotFoundDiagnostic, createNotImplementedDiagnostic, createPathTraversalDiagnostic, type ForgeDiagnosticInput, } from "./diagnostics";
+export { createForgeDiagnostic, createInvalidSnapshotDiagnostic, createInvalidPathDiagnostic, createMissingParentDiagnostic, createNotFoundDiagnostic, createNotImplementedDiagnostic, createPathTraversalDiagnostic, type ForgeDiagnosticInput, } from "./diagnostics";
 export { normalizeForgePath, type ForgePathNormalizationResult, } from "./path";
 export { ForgeFileSystemError } from "./errors";
 export { InMemoryVirtualFileSystem } from "./memory";
 export { createIndexedDbForgeStorage, FORGE_INDEXED_DB_NAME, FORGE_INDEXED_DB_STORES, FORGE_INDEXED_DB_VERSION, IndexedDbForgeStorage, type IndexedDbForgeStorageOptions, } from "./storage";
-export type { ForgeBuildCacheRecord, ForgeDeleteOptions, ForgeDiagnostic, ForgeDiagnosticCode, ForgeDiagnosticSeverity, ForgeDirEntry, ForgeFileCreatedEvent, ForgeFileDeletedEvent, ForgeFileEvent, ForgeFileKind, ForgeFileRecord, ForgeFileRenamedEvent, ForgeFileSource, ForgeFileStat, ForgeFileUpdatedEvent, ForgeFileWatchListener, ForgeLimitDiagnostic, ForgeMkdirOptions, ForgeOpenVirtualFileSystemOptions, ForgePackageCacheRecord, ForgePersistedWorkspace, ForgeVirtualFileSystemLimits, ResolvedForgeVirtualFileSystemLimits, ForgeRestoreOptions, ForgeSnapshot, ForgeSnapshotOptions, ForgeUnsubscribe, ForgeVirtualFileSystemOptions, ForgeVirtualFileSystemStorage, ForgeWorkspace, ForgeWorkspaceMetadata, ForgeWriteFileOptions, } from "./types";
+export { exportWorkspaceSnapshot, importWorkspaceSnapshot, } from "./snapshot-serialization";
+export { FORGE_WORKSPACE_SNAPSHOT_EXPORT_SCHEMA_VERSION } from "./types";
+export type { ForgeBuildCacheRecord, ForgeDeleteOptions, ForgeDiagnostic, ForgeDiagnosticCode, ForgeDiagnosticSeverity, ForgeDirEntry, ForgeFileCreatedEvent, ForgeFileDeletedEvent, ForgeFileEvent, ForgeFileKind, ForgeFileRecord, ForgeFileRenamedEvent, ForgeFileSource, ForgeFileStat, ForgeFileUpdatedEvent, ForgeFileWatchListener, ForgeLimitDiagnostic, ForgeMkdirOptions, ForgeOpenVirtualFileSystemOptions, ForgePackageCacheRecord, ForgePersistedWorkspace, ForgeSerializedFileRecord, ForgeSerializedWorkspaceSnapshot, ForgeSerializedWorkspaceSnapshotPayload, ForgeVirtualFileSystemLimits, ResolvedForgeVirtualFileSystemLimits, ForgeRestoreOptions, ForgeSnapshot, ForgeSnapshotOptions, ForgeUnsubscribe, ForgeVirtualFileSystemOptions, ForgeVirtualFileSystemStorage, ForgeWorkspace, ForgeWorkspaceMetadata, ForgeWorkspaceSnapshotExportOptions, ForgeWriteFileOptions, } from "./types";
 export declare const VIRTUAL_FILE_SYSTEM_CAPABILITY: "virtual-file-system";
 export interface ForgeVirtualFileSystem {
     readonly capability: typeof VIRTUAL_FILE_SYSTEM_CAPABILITY;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.openVirtualFileSystem = exports.createVirtualFileSystem = exports.VIRTUAL_FILE_SYSTEM_CAPABILITY = exports.IndexedDbForgeStorage = exports.FORGE_INDEXED_DB_VERSION = exports.FORGE_INDEXED_DB_STORES = exports.FORGE_INDEXED_DB_NAME = exports.createIndexedDbForgeStorage = exports.InMemoryVirtualFileSystem = exports.ForgeFileSystemError = exports.normalizeForgePath = exports.createPathTraversalDiagnostic = exports.createNotImplementedDiagnostic = exports.createNotFoundDiagnostic = exports.createMissingParentDiagnostic = exports.createInvalidPathDiagnostic = exports.createForgeDiagnostic = exports.resolveForgeVirtualFileSystemLimits = exports.createLimitExceededDiagnostic = exports.DEFAULT_FORGE_VFS_LIMITS = void 0;
+exports.openVirtualFileSystem = exports.createVirtualFileSystem = exports.VIRTUAL_FILE_SYSTEM_CAPABILITY = exports.FORGE_WORKSPACE_SNAPSHOT_EXPORT_SCHEMA_VERSION = exports.importWorkspaceSnapshot = exports.exportWorkspaceSnapshot = exports.IndexedDbForgeStorage = exports.FORGE_INDEXED_DB_VERSION = exports.FORGE_INDEXED_DB_STORES = exports.FORGE_INDEXED_DB_NAME = exports.createIndexedDbForgeStorage = exports.InMemoryVirtualFileSystem = exports.ForgeFileSystemError = exports.normalizeForgePath = exports.createPathTraversalDiagnostic = exports.createNotImplementedDiagnostic = exports.createNotFoundDiagnostic = exports.createMissingParentDiagnostic = exports.createInvalidPathDiagnostic = exports.createInvalidSnapshotDiagnostic = exports.createForgeDiagnostic = exports.resolveForgeVirtualFileSystemLimits = exports.createLimitExceededDiagnostic = exports.DEFAULT_FORGE_VFS_LIMITS = void 0;
 const memory_1 = require("./memory");
 const storage_1 = require("./storage");
 var limits_1 = require("./limits");
@@ -9,6 +9,7 @@ Object.defineProperty(exports, "createLimitExceededDiagnostic", { enumerable: tr
 Object.defineProperty(exports, "resolveForgeVirtualFileSystemLimits", { enumerable: true, get: function () { return limits_1.resolveForgeVirtualFileSystemLimits; } });
 var diagnostics_1 = require("./diagnostics");
 Object.defineProperty(exports, "createForgeDiagnostic", { enumerable: true, get: function () { return diagnostics_1.createForgeDiagnostic; } });
+Object.defineProperty(exports, "createInvalidSnapshotDiagnostic", { enumerable: true, get: function () { return diagnostics_1.createInvalidSnapshotDiagnostic; } });
 Object.defineProperty(exports, "createInvalidPathDiagnostic", { enumerable: true, get: function () { return diagnostics_1.createInvalidPathDiagnostic; } });
 Object.defineProperty(exports, "createMissingParentDiagnostic", { enumerable: true, get: function () { return diagnostics_1.createMissingParentDiagnostic; } });
 Object.defineProperty(exports, "createNotFoundDiagnostic", { enumerable: true, get: function () { return diagnostics_1.createNotFoundDiagnostic; } });
@@ -26,6 +27,11 @@ Object.defineProperty(exports, "FORGE_INDEXED_DB_NAME", { enumerable: true, get:
 Object.defineProperty(exports, "FORGE_INDEXED_DB_STORES", { enumerable: true, get: function () { return storage_2.FORGE_INDEXED_DB_STORES; } });
 Object.defineProperty(exports, "FORGE_INDEXED_DB_VERSION", { enumerable: true, get: function () { return storage_2.FORGE_INDEXED_DB_VERSION; } });
 Object.defineProperty(exports, "IndexedDbForgeStorage", { enumerable: true, get: function () { return storage_2.IndexedDbForgeStorage; } });
+var snapshot_serialization_1 = require("./snapshot-serialization");
+Object.defineProperty(exports, "exportWorkspaceSnapshot", { enumerable: true, get: function () { return snapshot_serialization_1.exportWorkspaceSnapshot; } });
+Object.defineProperty(exports, "importWorkspaceSnapshot", { enumerable: true, get: function () { return snapshot_serialization_1.importWorkspaceSnapshot; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "FORGE_WORKSPACE_SNAPSHOT_EXPORT_SCHEMA_VERSION", { enumerable: true, get: function () { return types_1.FORGE_WORKSPACE_SNAPSHOT_EXPORT_SCHEMA_VERSION; } });
 exports.VIRTUAL_FILE_SYSTEM_CAPABILITY = "virtual-file-system";
 function createVirtualFileSystem(options) {
     return new memory_1.InMemoryVirtualFileSystem(options);

package/dist/virtual-file-system/snapshot-serialization.d.ts

@@ -0,0 +1,3 @@
+import type { ForgeSerializedWorkspaceSnapshotPayload, ForgeSnapshot, ForgeWorkspaceSnapshotExportOptions } from "./types";
+export declare function exportWorkspaceSnapshot(snapshot: ForgeSnapshot, options?: ForgeWorkspaceSnapshotExportOptions): string;
+export declare function importWorkspaceSnapshot(payload: string | ForgeSerializedWorkspaceSnapshotPayload): ForgeSnapshot;

package/dist/virtual-file-system/snapshot-serialization.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importWorkspaceSnapshot = exports.exportWorkspaceSnapshot = void 0;
+const diagnostics_1 = require("./diagnostics");
+const errors_1 = require("./errors");
+const types_1 = require("./types");
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const BASE64_LOOKUP = createBase64Lookup();
+const VALID_FILE_KINDS = new Set(["file", "directory"]);
+const VALID_SNAPSHOT_SOURCES = new Set([
+    "generated",
+    "template",
+    "user",
+]);
+function exportWorkspaceSnapshot(snapshot, options = {}) {
+    const payload = {
+        schemaVersion: types_1.FORGE_WORKSPACE_SNAPSHOT_EXPORT_SCHEMA_VERSION,
+        snapshot: {
+            id: snapshot.id,
+            workspaceId: snapshot.workspaceId,
+            createdAt: snapshot.createdAt,
+            files: snapshot.files
+                .filter((file) => file.source !== "cache")
+                .map(serializeFileRecord)
+                .sort(compareSerializedFileRecords),
+            lock: snapshot.lock,
+            metadata: snapshot.metadata,
+        },
+    };
+    return stableStringify(payload, options.space);
+}
+exports.exportWorkspaceSnapshot = exportWorkspaceSnapshot;
+function importWorkspaceSnapshot(payload) {
+    const parsedPayload = typeof payload === "string" ? parseSnapshotPayload(payload) : payload;
+    assertPlainObject(parsedPayload, "Snapshot payload must be an object.");
+    assertEqual(parsedPayload.schemaVersion, types_1.FORGE_WORKSPACE_SNAPSHOT_EXPORT_SCHEMA_VERSION, "Snapshot payload schema version is unsupported.");
+    const snapshot = parsedPayload.snapshot;
+    assertPlainObject(snapshot, "Snapshot payload is missing snapshot data.");
+    assertString(snapshot.id, "Snapshot id must be a string.");
+    assertString(snapshot.workspaceId, "Snapshot workspace id must be a string.");
+    assertString(snapshot.createdAt, "Snapshot createdAt must be a string.");
+    assertArray(snapshot.files, "Snapshot files must be an array.");
+    return {
+        id: snapshot.id,
+        workspaceId: snapshot.workspaceId,
+        createdAt: snapshot.createdAt,
+        files: snapshot.files.map(importFileRecord),
+        lock: snapshot.lock,
+        metadata: snapshot.metadata === undefined
+            ? undefined
+            : importMetadata(snapshot.metadata),
+    };
+}
+exports.importWorkspaceSnapshot = importWorkspaceSnapshot;
+function parseSnapshotPayload(payload) {
+    try {
+        return JSON.parse(payload);
+    }
+    catch (cause) {
+        throw invalidSnapshot("Snapshot payload must be valid JSON.", cause);
+    }
+}
+function serializeFileRecord(file) {
+    return {
+        path: file.path,
+        kind: file.kind,
+        contentBase64: file.content === undefined ? undefined : encodeBase64(file.content),
+        contentType: file.contentType,
+        contentHash: file.contentHash,
+        size: file.size,
+        createdAt: file.createdAt,
+        updatedAt: file.updatedAt,
+        source: file.source,
+    };
+}
+function importFileRecord(file) {
+    assertPlainObject(file, "Snapshot file record must be an object.");
+    assertString(file.path, "Snapshot file path must be a string.");
+    assertString(file.kind, "Snapshot file kind must be a string.");
+    assertString(file.createdAt, "Snapshot file createdAt must be a string.");
+    assertString(file.updatedAt, "Snapshot file updatedAt must be a string.");
+    assertString(file.source, "Snapshot file source must be a string.");
+    assertNumber(file.size, "Snapshot file size must be a finite number.");
+    if (!VALID_FILE_KINDS.has(file.kind)) {
+        throw invalidSnapshot("Snapshot file kind is unsupported.");
+    }
+    if (!VALID_SNAPSHOT_SOURCES.has(file.source)) {
+        throw invalidSnapshot("Snapshot file source is unsupported.");
+    }
+    assertOptionalString(file.contentBase64, "Snapshot file content must be base64 text.");
+    assertOptionalString(file.contentType, "Snapshot file content type must be a string.");
+    assertOptionalString(file.contentHash, "Snapshot file content hash must be a string.");
+    return {
+        path: file.path,
+        kind: file.kind,
+        content: file.contentBase64 === undefined
+            ? undefined
+            : decodeBase64(file.contentBase64),
+        contentType: file.contentType,
+        contentHash: file.contentHash,
+        size: file.size,
+        createdAt: file.createdAt,
+        updatedAt: file.updatedAt,
+        source: file.source,
+    };
+}
+function importMetadata(metadata) {
+    assertPlainObject(metadata, "Snapshot metadata must be an object.");
+    return metadata;
+}
+function compareSerializedFileRecords(left, right) {
+    const pathOrder = left.path.localeCompare(right.path);
+    return pathOrder === 0 ? left.kind.localeCompare(right.kind) : pathOrder;
+}
+function stableStringify(value, space) {
+    return JSON.stringify(toStableJsonValue(value), undefined, space);
+}
+function toStableJsonValue(value, seen = new Set()) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const withToJson = value;
+    if (typeof withToJson.toJSON === "function") {
+        return toStableJsonValue(withToJson.toJSON(), seen);
+    }
+    if (seen.has(value)) {
+        throw new TypeError("Cannot serialize circular snapshot metadata.");
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        const result = value.map((item) => toStableJsonValue(item, seen));
+        seen.delete(value);
+        return result;
+    }
+    const record = value;
+    const result = {};
+    for (const key of Object.keys(record).sort()) {
+        const stableValue = toStableJsonValue(record[key], seen);
+        if (stableValue !== undefined) {
+            result[key] = stableValue;
+        }
+    }
+    seen.delete(value);
+    return result;
+}
+function encodeBase64(bytes) {
+    let output = "";
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index];
+        const second = bytes[index + 1];
+        const third = bytes[index + 2];
+        const hasSecond = index + 1 < bytes.length;
+        const hasThird = index + 2 < bytes.length;
+        const value = (first << 16) | ((hasSecond ? second : 0) << 8) | (hasThird ? third : 0);
+        output += BASE64_ALPHABET[(value >> 18) & 0x3f];
+        output += BASE64_ALPHABET[(value >> 12) & 0x3f];
+        output += hasSecond ? BASE64_ALPHABET[(value >> 6) & 0x3f] : "=";
+        output += hasThird ? BASE64_ALPHABET[value & 0x3f] : "=";
+    }
+    return output;
+}
+function decodeBase64(value) {
+    if (value.length === 0) {
+        return new Uint8Array();
+    }
+    if (value.length % 4 !== 0 ||
+        !/^[A-Za-z0-9+/]+={0,2}$/.test(value) ||
+        /=[A-Za-z0-9+/]/.test(value)) {
+        throw invalidSnapshot("Snapshot file content is not valid base64.");
+    }
+    const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+    const bytes = new Uint8Array((value.length / 4) * 3 - padding);
+    let byteIndex = 0;
+    for (let index = 0; index < value.length; index += 4) {
+        const first = base64Value(value[index]);
+        const second = base64Value(value[index + 1]);
+        const third = value[index + 2] === "=" ? 0 : base64Value(value[index + 2]);
+        const fourth = value[index + 3] === "=" ? 0 : base64Value(value[index + 3]);
+        const packed = (first << 18) | (second << 12) | (third << 6) | fourth;
+        if (byteIndex < bytes.length) {
+            bytes[byteIndex] = (packed >> 16) & 0xff;
+            byteIndex += 1;
+        }
+        if (byteIndex < bytes.length) {
+            bytes[byteIndex] = (packed >> 8) & 0xff;
+            byteIndex += 1;
+        }
+        if (byteIndex < bytes.length) {
+            bytes[byteIndex] = packed & 0xff;
+            byteIndex += 1;
+        }
+    }
+    if (encodeBase64(bytes) !== value) {
+        throw invalidSnapshot("Snapshot file content is not canonical base64.");
+    }
+    return bytes;
+}
+function base64Value(character) {
+    const value = BASE64_LOOKUP.get(character);
+    if (value === undefined) {
+        throw invalidSnapshot("Snapshot file content is not valid base64.");
+    }
+    return value;
+}
+function createBase64Lookup() {
+    return new Map(Array.from(BASE64_ALPHABET, (character, index) => [character, index]));
+}
+function assertPlainObject(value, message) {
+    if (value === null ||
+        typeof value !== "object" ||
+        Array.isArray(value)) {
+        throw invalidSnapshot(message);
+    }
+}
+function assertString(value, message) {
+    if (typeof value !== "string") {
+        throw invalidSnapshot(message);
+    }
+}
+function assertOptionalString(value, message) {
+    if (value !== undefined && typeof value !== "string") {
+        throw invalidSnapshot(message);
+    }
+}
+function assertNumber(value, message) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw invalidSnapshot(message);
+    }
+}
+function assertArray(value, message) {
+    if (!Array.isArray(value)) {
+        throw invalidSnapshot(message);
+    }
+}
+function assertEqual(actual, expected, message) {
+    if (actual !== expected) {
+        throw invalidSnapshot(message);
+    }
+}
+function invalidSnapshot(message, cause) {
+    return new errors_1.ForgeFileSystemError((0, diagnostics_1.createInvalidSnapshotDiagnostic)(message, cause));
+}

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

@@ -26,7 +26,7 @@ export declare class IndexedDbForgeStorage implements ForgeVirtualFileSystemStor
     clearBuildCache(): Promise<void>;
     private getCacheRecord;
     private putCacheRecord;
-    private assertCacheLimit;
+    private cacheLimitMaximum;
     private openDatabase;
 }
 export declare function createIndexedDbForgeStorage(options?: IndexedDbForgeStorageOptions): IndexedDbForgeStorage;

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

@@ -100,30 +100,21 @@ class IndexedDbForgeStorage {
         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);
+        const objectStore = transaction.objectStore(storeName);
+        const existingRecords = await requestToPromise(objectStore.getAll());
+        const evictionKeys = planCacheEviction(storeName, record, existingRecords, this.cacheLimitMaximum(storeName));
+        for (const key of evictionKeys) {
+            objectStore.delete(key);
+        }
+        objectStore.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
+    cacheLimitMaximum(storeName) {
+        return 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) {
@@ -149,6 +140,38 @@ function createIndexedDbForgeStorage(options) {
     return new IndexedDbForgeStorage(options);
 }
 exports.createIndexedDbForgeStorage = createIndexedDbForgeStorage;
+function planCacheEviction(storeName, record, existingRecords, maximum) {
+    const limitName = storeName === exports.FORGE_INDEXED_DB_STORES.packageCache
+        ? "packageCacheSize"
+        : "buildCacheSize";
+    if (record.size > maximum) {
+        throw new errors_1.ForgeFileSystemError((0, limits_1.createLimitExceededDiagnostic)(limitName, record.size, maximum));
+    }
+    const candidates = existingRecords
+        .filter((existingRecord) => existingRecord.key !== record.key)
+        .sort(compareCacheRecordsForEviction);
+    let projectedSize = candidates.reduce((total, existingRecord) => total + existingRecord.size, 0) +
+        record.size;
+    if (projectedSize <= maximum) {
+        return [];
+    }
+    const evictionKeys = [];
+    for (const candidate of candidates) {
+        evictionKeys.push(candidate.key);
+        projectedSize -= candidate.size;
+        if (projectedSize <= maximum) {
+            return evictionKeys;
+        }
+    }
+    throw new errors_1.ForgeFileSystemError((0, limits_1.createLimitExceededDiagnostic)(limitName, projectedSize, maximum));
+}
+function compareCacheRecordsForEviction(left, right) {
+    const updatedAtComparison = left.updatedAt.localeCompare(right.updatedAt);
+    if (updatedAtComparison !== 0) {
+        return updatedAtComparison;
+    }
+    return left.key.localeCompare(right.key);
+}
 function ensureStores(database) {
     if (!database.objectStoreNames.contains(exports.FORGE_INDEXED_DB_STORES.workspaceMetadata)) {
         database.createObjectStore(exports.FORGE_INDEXED_DB_STORES.workspaceMetadata, {

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

@@ -47,8 +47,35 @@ export interface ForgeSnapshot {
     readonly lock?: unknown;
     readonly metadata?: Record<string, unknown>;
 }
+export declare const FORGE_WORKSPACE_SNAPSHOT_EXPORT_SCHEMA_VERSION = 1;
+export interface ForgeWorkspaceSnapshotExportOptions {
+    readonly space?: number;
+}
+export interface ForgeSerializedWorkspaceSnapshotPayload {
+    readonly schemaVersion: typeof FORGE_WORKSPACE_SNAPSHOT_EXPORT_SCHEMA_VERSION;
+    readonly snapshot: ForgeSerializedWorkspaceSnapshot;
+}
+export interface ForgeSerializedWorkspaceSnapshot {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly createdAt: string;
+    readonly files: readonly ForgeSerializedFileRecord[];
+    readonly lock?: unknown;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface ForgeSerializedFileRecord {
+    readonly path: string;
+    readonly kind: ForgeFileKind;
+    readonly contentBase64?: string;
+    readonly contentType?: string;
+    readonly contentHash?: string;
+    readonly size: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly source: Exclude<ForgeFileSource, "cache">;
+}
 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 type ForgeDiagnosticCode = "already_exists" | "directory_not_empty" | "invalid_snapshot" | "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;

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caryhu/codemine-forge",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.2",
   "description": "Browser-side runtime layer for Codemine demos.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,7 +34,7 @@
     "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": "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/vue-vite-template-dev-loop.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",