@caryhu/codemine-forge 0.0.1-alpha.0

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

@@ -0,0 +1,551 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryVirtualFileSystem = void 0;
+const diagnostics_1 = require("./diagnostics");
+const errors_1 = require("./errors");
+const limits_1 = require("./limits");
+const path_1 = require("./path");
+class InMemoryVirtualFileSystem {
+    constructor(options = {}) {
+        this.capability = "virtual-file-system";
+        this.watchers = new Set();
+        const now = timestamp();
+        this.workspaceId = options.workspaceId ?? "default";
+        this.workspaceName = options.workspaceName ?? "Untitled Workspace";
+        this.lock = options.lock;
+        this.storage = options.storage;
+        this.limits = (0, limits_1.resolveForgeVirtualFileSystemLimits)(options.limits);
+        this.metadata = options.metadata ?? {
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.records = createInitialRecords(now, options.files);
+    }
+    async readFile(path) {
+        const record = this.requireFile(path);
+        return copyBytes(record.content ?? new Uint8Array());
+    }
+    async readText(path) {
+        return new TextDecoder().decode(await this.readFile(path));
+    }
+    async writeFile(path, content, options = {}) {
+        const normalizedPath = this.normalize(path);
+        const parentPath = getParentPath(normalizedPath);
+        const parent = this.records.get(parentPath);
+        if (parent === undefined) {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createMissingParentDiagnostic)(path));
+        }
+        if (parent.kind !== "directory") {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "not_directory",
+                message: "Parent path is not a directory.",
+                path: parentPath,
+            }));
+        }
+        const existing = this.records.get(normalizedPath);
+        if (existing?.kind === "directory") {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "is_directory",
+                message: "Cannot write file content to a directory.",
+                path: normalizedPath,
+            }));
+        }
+        const bytes = toBytes(content);
+        this.assertLimit("fileSize", bytes.byteLength, this.limits.maxFileSizeBytes, normalizedPath);
+        const now = timestamp();
+        const next = cloneRecords(this.records);
+        const nextRecord = {
+            path: normalizedPath,
+            kind: "file",
+            content: copyBytes(bytes),
+            contentType: options.contentType,
+            contentHash: hashBytes(bytes),
+            size: bytes.byteLength,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            source: options.source ?? existing?.source ?? "user",
+        };
+        next.set(normalizedPath, nextRecord);
+        await this.commit(next, [
+            existing === undefined
+                ? {
+                    type: "file:created",
+                    path: normalizedPath,
+                    stat: toStat(nextRecord),
+                }
+                : {
+                    type: "file:updated",
+                    path: normalizedPath,
+                    stat: toStat(nextRecord),
+                    previousHash: existing.contentHash,
+                },
+        ]);
+    }
+    async delete(path, options = {}) {
+        const normalizedPath = this.normalize(path);
+        if (normalizedPath === "/") {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createInvalidPathDiagnostic)(path, "Cannot delete the workspace root."));
+        }
+        const deletedRecord = this.requireRecord(normalizedPath);
+        const descendantPrefix = `${normalizedPath}/`;
+        const descendants = Array.from(this.records.keys()).filter((recordPath) => recordPath.startsWith(descendantPrefix));
+        if (descendants.length > 0 && options.recursive !== true) {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "directory_not_empty",
+                message: "Directory is not empty.",
+                path: normalizedPath,
+            }));
+        }
+        const next = cloneRecords(this.records);
+        next.delete(normalizedPath);
+        for (const descendant of descendants) {
+            next.delete(descendant);
+        }
+        await this.commit(next, [
+            {
+                type: "file:deleted",
+                path: normalizedPath,
+                stat: toStat(deletedRecord),
+            },
+        ]);
+    }
+    async rename(from, to) {
+        const normalizedFrom = this.normalize(from);
+        const normalizedTo = this.normalize(to);
+        if (normalizedFrom === "/" || normalizedTo === "/") {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createInvalidPathDiagnostic)(from, "Cannot rename the workspace root."));
+        }
+        if (normalizedTo.startsWith(`${normalizedFrom}/`)) {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createInvalidPathDiagnostic)(to, "Cannot rename a directory into one of its descendants."));
+        }
+        const source = this.requireRecord(normalizedFrom);
+        const targetParentPath = getParentPath(normalizedTo);
+        const targetParent = this.records.get(targetParentPath);
+        if (targetParent === undefined) {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createMissingParentDiagnostic)(to));
+        }
+        if (targetParent.kind !== "directory") {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "not_directory",
+                message: "Target parent path is not a directory.",
+                path: targetParentPath,
+            }));
+        }
+        if (this.records.has(normalizedTo)) {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "already_exists",
+                message: "Target path already exists.",
+                path: normalizedTo,
+                relatedPath: normalizedFrom,
+            }));
+        }
+        const now = timestamp();
+        const next = cloneRecords(this.records);
+        const prefix = `${normalizedFrom}/`;
+        const movedEntries = [];
+        for (const [recordPath, record] of this.records) {
+            if (recordPath === normalizedFrom || recordPath.startsWith(prefix)) {
+                const suffix = recordPath.slice(normalizedFrom.length);
+                const movedPath = `${normalizedTo}${suffix}`;
+                if (recordPath !== normalizedFrom && this.records.has(movedPath)) {
+                    throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                        code: "already_exists",
+                        message: "Renamed path would overwrite an existing record.",
+                        path: movedPath,
+                        relatedPath: normalizedFrom,
+                    }));
+                }
+                movedEntries.push([
+                    movedPath,
+                    {
+                        ...record,
+                        path: movedPath,
+                        updatedAt: now,
+                        content: copyOptionalBytes(record.content),
+                    },
+                ]);
+                next.delete(recordPath);
+            }
+        }
+        next.set(normalizedTo, {
+            ...source,
+            path: normalizedTo,
+            updatedAt: now,
+            content: copyOptionalBytes(source.content),
+        });
+        for (const [movedPath, movedRecord] of movedEntries) {
+            next.set(movedPath, movedRecord);
+        }
+        const renamedRecord = next.get(normalizedTo);
+        await this.commit(next, [
+            {
+                type: "file:renamed",
+                from: normalizedFrom,
+                to: normalizedTo,
+                stat: toStat(renamedRecord ?? source),
+            },
+        ]);
+    }
+    async mkdir(path, options = {}) {
+        const normalizedPath = this.normalize(path);
+        if (normalizedPath === "/" || this.records.has(normalizedPath)) {
+            const existing = this.records.get(normalizedPath);
+            if (existing?.kind === "directory") {
+                return;
+            }
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "already_exists",
+                message: "Path already exists and is not a directory.",
+                path: normalizedPath,
+            }));
+        }
+        const missingParents = collectMissingParents(normalizedPath, this.records);
+        if (missingParents.length > 0 && options.recursive !== true) {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createMissingParentDiagnostic)(path));
+        }
+        const now = timestamp();
+        const next = cloneRecords(this.records);
+        const directories = [...missingParents, normalizedPath];
+        const events = [];
+        for (const directoryPath of directories) {
+            if (!next.has(directoryPath)) {
+                const nextRecord = {
+                    path: directoryPath,
+                    kind: "directory",
+                    size: 0,
+                    createdAt: now,
+                    updatedAt: now,
+                    source: options.source ?? "user",
+                };
+                next.set(directoryPath, nextRecord);
+                events.push({
+                    type: "file:created",
+                    path: directoryPath,
+                    stat: toStat(nextRecord),
+                });
+            }
+        }
+        await this.commit(next, events);
+    }
+    async readdir(path) {
+        const normalizedPath = this.normalize(path);
+        const directory = this.requireRecord(normalizedPath);
+        if (directory.kind !== "directory") {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "not_directory",
+                message: "Path is not a directory.",
+                path: normalizedPath,
+            }));
+        }
+        const entries = [];
+        const prefix = normalizedPath === "/" ? "/" : `${normalizedPath}/`;
+        for (const [recordPath, record] of this.records) {
+            if (recordPath === normalizedPath || !recordPath.startsWith(prefix)) {
+                continue;
+            }
+            const relativePath = recordPath.slice(prefix.length);
+            if (relativePath.includes("/")) {
+                continue;
+            }
+            entries.push({
+                name: relativePath,
+                path: recordPath,
+                kind: record.kind,
+                stat: toStat(record),
+            });
+        }
+        return entries.sort((left, right) => left.name.localeCompare(right.name));
+    }
+    async stat(path) {
+        return toStat(this.requireRecord(this.normalize(path)));
+    }
+    async exists(path) {
+        const normalizedPath = this.normalize(path);
+        return this.records.has(normalizedPath);
+    }
+    async snapshot(options = {}) {
+        return {
+            id: `snapshot-${Date.now()}`,
+            workspaceId: this.workspaceId,
+            createdAt: timestamp(),
+            files: recordsToFileRecords(this.records).filter((file) => shouldIncludeInSnapshot(file, options)),
+            lock: options.includeRuntimeMetadata === false ? undefined : this.lock,
+            metadata: {
+                workspaceName: this.workspaceName,
+            },
+        };
+    }
+    async restore(snapshot, _options) {
+        const now = timestamp();
+        const next = createInitialRecords(now);
+        for (const record of this.records.values()) {
+            if (record.path !== "/" && record.source === "cache") {
+                next.set(record.path, {
+                    ...record,
+                    content: copyOptionalBytes(record.content),
+                });
+            }
+        }
+        for (const file of snapshot.files) {
+            if (file.path === "/" || file.source === "cache") {
+                continue;
+            }
+            const normalizedPath = this.normalize(file.path);
+            next.set(normalizedPath, {
+                path: normalizedPath,
+                kind: file.kind,
+                content: copyOptionalBytes(file.content),
+                contentType: file.contentType,
+                contentHash: file.contentHash,
+                size: file.size,
+                createdAt: file.createdAt,
+                updatedAt: file.updatedAt,
+                source: file.source,
+            });
+        }
+        await this.commit(next, createRestoreEvents(this.records, next));
+    }
+    watch(listener) {
+        this.watchers.add(listener);
+        return () => {
+            this.watchers.delete(listener);
+        };
+    }
+    normalize(path) {
+        const result = (0, path_1.normalizeForgePath)(path);
+        if (result.ok) {
+            return result.path;
+        }
+        throw new errors_1.ForgeFileSystemError(result.diagnostic);
+    }
+    requireRecord(path) {
+        const record = this.records.get(path);
+        if (record === undefined) {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createNotFoundDiagnostic)(path));
+        }
+        return record;
+    }
+    requireFile(path) {
+        const normalizedPath = this.normalize(path);
+        const record = this.requireRecord(normalizedPath);
+        if (record.kind !== "file") {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "not_file",
+                message: "Path is not a file.",
+                path: normalizedPath,
+            }));
+        }
+        return record;
+    }
+    async commit(next, events = []) {
+        this.assertWorkspaceLimits(next);
+        const metadata = {
+            ...this.metadata,
+            updatedAt: timestamp(),
+        };
+        if (this.storage !== undefined) {
+            await this.storage.saveWorkspace({
+                id: this.workspaceId,
+                name: this.workspaceName,
+                files: recordsToFileRecords(next).filter((file) => file.source !== "cache"),
+                metadata,
+                lock: this.lock,
+            });
+        }
+        this.records = next;
+        this.metadata = metadata;
+        this.emit(events);
+    }
+    assertWorkspaceLimits(records) {
+        this.assertLimit("workspaceSize", workspaceSize(records), this.limits.maxWorkspaceSizeBytes);
+        this.assertLimit("fileCount", fileCount(records), this.limits.maxFileCount);
+    }
+    assertLimit(name, actual, maximum, path) {
+        if (actual > maximum) {
+            throw new errors_1.ForgeFileSystemError((0, limits_1.createLimitExceededDiagnostic)(name, actual, maximum, path));
+        }
+    }
+    emit(events) {
+        for (const event of events) {
+            for (const watcher of this.watchers) {
+                try {
+                    watcher(event);
+                }
+                catch {
+                    // Watchers are observers; one listener must not roll back a commit.
+                }
+            }
+        }
+    }
+}
+exports.InMemoryVirtualFileSystem = InMemoryVirtualFileSystem;
+function createInitialRecords(createdAt, files = []) {
+    const records = new Map([
+        [
+            "/",
+            {
+                path: "/",
+                kind: "directory",
+                size: 0,
+                createdAt,
+                updatedAt: createdAt,
+                source: "user",
+            },
+        ],
+    ]);
+    for (const file of files) {
+        if (file.path === "/") {
+            continue;
+        }
+        records.set(file.path, {
+            path: file.path,
+            kind: file.kind,
+            content: copyOptionalBytes(file.content),
+            contentType: file.contentType,
+            contentHash: file.contentHash,
+            size: file.size,
+            createdAt: file.createdAt,
+            updatedAt: file.updatedAt,
+            source: file.source,
+        });
+    }
+    return records;
+}
+function cloneRecords(records) {
+    return new Map(Array.from(records, ([path, record]) => [
+        path,
+        {
+            ...record,
+            content: copyOptionalBytes(record.content),
+        },
+    ]));
+}
+function collectMissingParents(path, records) {
+    const parts = path.split("/").filter(Boolean);
+    const missing = [];
+    for (let index = 1; index < parts.length; index += 1) {
+        const parentPath = `/${parts.slice(0, index).join("/")}`;
+        const parent = records.get(parentPath);
+        if (parent === undefined) {
+            missing.push(parentPath);
+            continue;
+        }
+        if (parent.kind !== "directory") {
+            throw new errors_1.ForgeFileSystemError((0, diagnostics_1.createForgeDiagnostic)({
+                code: "not_directory",
+                message: "Parent path is not a directory.",
+                path: parentPath,
+            }));
+        }
+    }
+    return missing;
+}
+function getParentPath(path) {
+    const lastSlashIndex = path.lastIndexOf("/");
+    return lastSlashIndex <= 0 ? "/" : path.slice(0, lastSlashIndex);
+}
+function toBytes(content) {
+    return typeof content === "string"
+        ? new TextEncoder().encode(content)
+        : copyBytes(content);
+}
+function copyBytes(bytes) {
+    return new Uint8Array(bytes);
+}
+function copyOptionalBytes(bytes) {
+    return bytes === undefined ? undefined : copyBytes(bytes);
+}
+function hashBytes(bytes) {
+    let hash = 0x811c9dc5;
+    for (const byte of bytes) {
+        hash ^= byte;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return `fnv1a32:${hash.toString(16).padStart(8, "0")}`;
+}
+function timestamp() {
+    return new Date().toISOString();
+}
+function toStat(record) {
+    return {
+        path: record.path,
+        kind: record.kind,
+        contentType: record.contentType,
+        contentHash: record.contentHash,
+        size: record.size,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        source: record.source,
+    };
+}
+function toFileRecord(record) {
+    return {
+        ...toStat(record),
+        content: copyOptionalBytes(record.content),
+    };
+}
+function recordsToFileRecords(records) {
+    return Array.from(records.values(), toFileRecord);
+}
+function workspaceSize(records) {
+    let size = 0;
+    for (const record of records.values()) {
+        if (record.kind === "file" && record.source !== "cache") {
+            size += record.size;
+        }
+    }
+    return size;
+}
+function fileCount(records) {
+    let count = 0;
+    for (const record of records.values()) {
+        if (record.kind === "file" && record.source !== "cache") {
+            count += 1;
+        }
+    }
+    return count;
+}
+function shouldIncludeInSnapshot(file, options) {
+    if (file.path === "/" || file.source === "cache") {
+        return false;
+    }
+    if (file.source === "generated" && options.includeGeneratedFiles !== true) {
+        return file.path === "/package.json";
+    }
+    return true;
+}
+function createRestoreEvents(previous, next) {
+    const events = [];
+    for (const [path, record] of previous) {
+        if (path !== "/" && record.source !== "cache" && !next.has(path)) {
+            events.push({
+                type: "file:deleted",
+                path,
+                stat: toStat(record),
+            });
+        }
+    }
+    for (const [path, record] of next) {
+        if (path === "/" || record.source === "cache") {
+            continue;
+        }
+        const previousRecord = previous.get(path);
+        if (previousRecord === undefined) {
+            events.push({
+                type: "file:created",
+                path,
+                stat: toStat(record),
+            });
+            continue;
+        }
+        if (previousRecord.contentHash !== record.contentHash) {
+            events.push({
+                type: "file:updated",
+                path,
+                stat: toStat(record),
+                previousHash: previousRecord.contentHash,
+            });
+        }
+    }
+    return events;
+}

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

@@ -0,0 +1,9 @@
+import type { ForgeDiagnostic } from "./types";
+export type ForgePathNormalizationResult = {
+    readonly ok: true;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly diagnostic: ForgeDiagnostic;
+};
+export declare function normalizeForgePath(path: string): ForgePathNormalizationResult;

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

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeForgePath = void 0;
+const diagnostics_1 = require("./diagnostics");
+function normalizeForgePath(path) {
+    if (typeof path !== "string" || path.length === 0) {
+        return {
+            ok: false,
+            diagnostic: (0, diagnostics_1.createInvalidPathDiagnostic)(String(path), "Path must be a non-empty string."),
+        };
+    }
+    if (path.includes("\0")) {
+        return {
+            ok: false,
+            diagnostic: (0, diagnostics_1.createInvalidPathDiagnostic)(path, "Path cannot contain null bytes."),
+        };
+    }
+    if (path.includes("\\")) {
+        return {
+            ok: false,
+            diagnostic: (0, diagnostics_1.createInvalidPathDiagnostic)(path, "Path must use POSIX forward slashes."),
+        };
+    }
+    const absolutePath = path.startsWith("/") ? path : `/${path}`;
+    const segments = [];
+    for (const segment of absolutePath.split("/")) {
+        if (segment.length === 0 || segment === ".") {
+            continue;
+        }
+        if (segment === "..") {
+            if (segments.length === 0) {
+                return {
+                    ok: false,
+                    diagnostic: (0, diagnostics_1.createPathTraversalDiagnostic)(path),
+                };
+            }
+            segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    return {
+        ok: true,
+        path: segments.length === 0 ? "/" : `/${segments.join("/")}`,
+    };
+}
+exports.normalizeForgePath = normalizeForgePath;

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

@@ -0,0 +1,32 @@
+import type { ForgeBuildCacheRecord, ForgePackageCacheRecord, ForgePersistedWorkspace, ForgeVirtualFileSystemLimits, ForgeVirtualFileSystemStorage } from "./types";
+export declare const FORGE_INDEXED_DB_NAME = "codemine-forge";
+export declare const FORGE_INDEXED_DB_VERSION = 1;
+export declare const FORGE_INDEXED_DB_STORES: {
+    readonly buildCache: "build-cache";
+    readonly packageCache: "package-cache";
+    readonly workspaceFiles: "workspace-files";
+    readonly workspaceMetadata: "workspace-metadata";
+    readonly workspaceSnapshots: "workspace-snapshots";
+};
+export interface IndexedDbForgeStorageOptions {
+    readonly databaseName?: string;
+    readonly limits?: ForgeVirtualFileSystemLimits;
+}
+export declare class IndexedDbForgeStorage implements ForgeVirtualFileSystemStorage {
+    private readonly databaseName;
+    private readonly limits;
+    private databasePromise;
+    constructor(options?: IndexedDbForgeStorageOptions);
+    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>;
+    private getCacheRecord;
+    private putCacheRecord;
+    private assertCacheLimit;
+    private openDatabase;
+}
+export declare function createIndexedDbForgeStorage(options?: IndexedDbForgeStorageOptions): IndexedDbForgeStorage;