@hakobu/hakobu 1.0.0

package/lib-es5/snapshot-index.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Hakobu Snapshot Index
+ *
+ * The snapshot index is the structural contract between the packaging
+ * pipeline and the runtime. It describes every file in the snapshot,
+ * every package boundary, and enough metadata for the runtime to:
+ *
+ *   - serve fs operations (readFile, stat, readdir, realpath)
+ *   - determine module format per-file (ESM vs CJS)
+ *   - resolve imports through package.json exports/imports maps
+ *   - construct canonical file: URLs for import.meta.url
+ *   - extract native addons to the real filesystem
+ *
+ * Invariants:
+ *   1. DETERMINISTIC: identical manifest → identical index → identical blob.
+ *      Entries are sorted by snapshot path (lexicographic, POSIX).
+ *   2. POSIX-NORMALIZED: all paths use '/' separators and are absolute
+ *      within the snapshot root (/snapshot/{appId}/...). The runtime
+ *      projects these to platform-native paths at execution time.
+ *   3. NO HOST PATHS: the index never contains host filesystem paths.
+ *      The manifest's absolutePath is consumed during blob assembly
+ *      and does not appear in the index.
+ *   4. SELF-CONTAINED for resolution: the index carries enough package
+ *      metadata to resolve imports without re-reading package.json
+ *      from the blob. This is critical for ESM loader performance.
+ *
+ * Lifecycle:
+ *   PackagingManifest → buildSnapshotIndex() → SnapshotIndex
+ *                                                   ↓
+ *                               (Task 5.2) blob assembly + fs hooks
+ *                                                   ↓
+ *                               (Task 6) ESM loader reads the index
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSnapshotIndex = void 0;
+// ─────────────────────────────────────────────────────────────────────
+// Builder: PackagingManifest → SnapshotIndex
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Build a SnapshotIndex from a PackagingManifest.
+ *
+ * This function:
+ * 1. Sorts entries deterministically by snapshot path
+ * 2. Computes byte offsets (sequential, no gaps)
+ * 3. Converts package metadata to runtime-optimized boundaries
+ * 4. Builds the directory tree for readdir/stat
+ *
+ * Content hashes and sizes must be populated in the manifest files.
+ * If they are not (e.g., during dry-run analysis), the index is still
+ * structurally valid but offset/size/hash fields will be zero/empty.
+ */
+function buildSnapshotIndex(manifest, fileSizes) {
+    // ── Sort entries deterministically ──
+    const sortedPaths = Object.keys(manifest.files).sort();
+    // ── Build entries with sequential offsets ──
+    let currentOffset = 0;
+    const entries = [];
+    for (const snapshotPath of sortedPaths) {
+        const file = manifest.files[snapshotPath];
+        const sizeInfo = fileSizes.get(snapshotPath) ?? { size: 0, hash: '' };
+        entries.push({
+            path: snapshotPath,
+            kind: file.kind,
+            format: file.format,
+            packageBoundary: file.packageBoundary,
+            offset: currentOffset,
+            size: sizeInfo.size,
+            contentHash: sizeInfo.hash,
+        });
+        currentOffset += sizeInfo.size;
+    }
+    // ── Build package boundaries ──
+    const packages = {};
+    for (const [snapshotPath, meta] of Object.entries(manifest.packages)) {
+        const dir = snapshotPath.replace(/\/package\.json$/, '');
+        packages[snapshotPath] = {
+            path: snapshotPath,
+            name: meta.name,
+            version: meta.version,
+            type: meta.type,
+            main: meta.main,
+            exports: meta.exports,
+            imports: meta.imports,
+            directory: dir,
+        };
+    }
+    // ── Build directory tree ──
+    const directories = buildDirectoryTree(entries);
+    return {
+        appId: manifest.appId,
+        entrypoint: manifest.entry.snapshotPath,
+        entrypointFormat: manifest.entry.format,
+        entries,
+        packages,
+        directories,
+        blobSize: currentOffset,
+    };
+}
+exports.buildSnapshotIndex = buildSnapshotIndex;
+// ─────────────────────────────────────────────────────────────────────
+// Directory tree builder
+// ─────────────────────────────────────────────────────────────────────
+function buildDirectoryTree(entries) {
+    const dirs = new Map();
+    function ensureDir(dirPath) {
+        if (!dirs.has(dirPath)) {
+            dirs.set(dirPath, { files: new Set(), directories: new Set() });
+        }
+        // Register this directory in its parent
+        const parent = dirPath.substring(0, dirPath.lastIndexOf('/')) || '/';
+        if (parent !== dirPath) {
+            ensureDir(parent);
+            const name = dirPath.substring(dirPath.lastIndexOf('/') + 1);
+            dirs.get(parent).directories.add(name);
+        }
+    }
+    for (const entry of entries) {
+        const dirPath = entry.path.substring(0, entry.path.lastIndexOf('/'));
+        const fileName = entry.path.substring(entry.path.lastIndexOf('/') + 1);
+        ensureDir(dirPath);
+        dirs.get(dirPath).files.add(fileName);
+    }
+    // Convert to sorted arrays for determinism
+    const result = {};
+    for (const [dirPath, contents] of dirs) {
+        result[dirPath] = {
+            path: dirPath,
+            files: [...contents.files].sort(),
+            directories: [...contents.directories].sort(),
+        };
+    }
+    return result;
+}
+//# sourceMappingURL=snapshot-index.js.map

package/lib-es5/snapshot-path.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Hakobu Snapshot Path Canonicalization
+ *
+ * Canonical rules:
+ *
+ * 1. INTERNAL FORM is always POSIX: /snapshot/{appId}/path/to/file.js
+ *    - Forward slashes only
+ *    - No drive letter
+ *    - No trailing slash (except root "/")
+ *    - No duplicate slashes
+ *    - No . or .. segments (resolved)
+ *    - Case-sensitive for all path segments
+ *
+ * 2. PLATFORM-NATIVE FORM is what Node's fs module sees:
+ *    - POSIX: /snapshot/{appId}/path/to/file.js (same as internal)
+ *    - Windows: C:\snapshot\{appId}\path\to\file.js
+ *
+ * 3. DETECTION accepts any platform variation:
+ *    - /snapshot/...
+ *    - C:\snapshot\... (any drive letter case)
+ *    - C:/snapshot/... (mixed separators)
+ *    - Paths with . and .. segments that resolve into /snapshot/
+ *
+ * 4. CASE SENSITIVITY:
+ *    - The "snapshot" prefix is case-insensitive on Windows only
+ *    - All path segments below /snapshot/ are case-sensitive on all
+ *      platforms (Node module resolution is case-sensitive)
+ *
+ * These utilities are used by:
+ * - snapshot-fs.ts (SnapshotFS lookups)
+ * - snapshot-fs-patch.ts (routing decisions)
+ * - snapshot-index.ts (index key computation)
+ * - (future) ESM loader (import.meta.url construction)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotJoin = exports.snapshotRoot = exports.fromFileUrl = exports.toFileUrl = exports.toNative = exports.toCanonical = exports.isSnapshotPath = void 0;
+const IS_WIN = process.platform === 'win32';
+// ─────────────────────────────────────────────────────────────────────
+// Detection
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Check if a path is inside the snapshot filesystem.
+ * Accepts any platform-native form, including mixed separators.
+ */
+function isSnapshotPath(p) {
+    // Normalize for detection: lowercase, forward slashes
+    const norm = p.replace(/\\/g, '/');
+    const lower = norm.toLowerCase();
+    // Strip drive letter for matching
+    const noPrefix = /^[a-z]:/.test(lower) ? lower.slice(2) : lower;
+    return noPrefix === '/snapshot' ||
+        noPrefix.startsWith('/snapshot/');
+}
+exports.isSnapshotPath = isSnapshotPath;
+// ─────────────────────────────────────────────────────────────────────
+// Canonicalization
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Convert any snapshot path form to canonical POSIX internal form.
+ *
+ * Input: any valid snapshot path (native or mixed)
+ * Output: /snapshot/{appId}/path/to/file (no trailing slash, no ./..)
+ *
+ * Throws if the input is not a snapshot path.
+ */
+function toCanonical(nativePath) {
+    // Replace all backslashes with forward slashes
+    let p = nativePath.replace(/\\/g, '/');
+    // Strip drive letter (e.g., C: or c:)
+    if (/^[A-Za-z]:/.test(p)) {
+        p = p.slice(2);
+    }
+    // Resolve . and .. segments, collapse duplicate slashes
+    const parts = p.split('/');
+    const resolved = [];
+    for (const part of parts) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            // Don't resolve above the root
+            if (resolved.length > 0 && resolved[resolved.length - 1] !== '') {
+                resolved.pop();
+            }
+            continue;
+        }
+        resolved.push(part);
+    }
+    const result = '/' + resolved.join('/');
+    // Remove trailing slash (except bare "/")
+    if (result.length > 1 && result.endsWith('/')) {
+        return result.slice(0, -1);
+    }
+    return result;
+}
+exports.toCanonical = toCanonical;
+// ─────────────────────────────────────────────────────────────────────
+// Platform conversion
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Convert a canonical POSIX path to platform-native form.
+ * - POSIX: returns the path unchanged
+ * - Windows: prepends C: and replaces / with \
+ */
+function toNative(posixPath) {
+    if (IS_WIN) {
+        return 'C:' + posixPath.replace(/\//g, '\\');
+    }
+    return posixPath;
+}
+exports.toNative = toNative;
+/**
+ * Construct a file: URL from a canonical snapshot path.
+ * Used for import.meta.url in ESM modules.
+ *
+ * POSIX: file:///snapshot/app/src/index.js
+ * Windows: file:///C:/snapshot/app/src/index.js
+ */
+function toFileUrl(posixPath) {
+    if (IS_WIN) {
+        return 'file:///C:' + posixPath;
+    }
+    return 'file://' + posixPath;
+}
+exports.toFileUrl = toFileUrl;
+/**
+ * Extract the canonical POSIX path from a file: URL.
+ * Returns null if the URL doesn't point into the snapshot.
+ */
+function fromFileUrl(url) {
+    if (!url.startsWith('file://'))
+        return null;
+    let p;
+    if (url.startsWith('file:///') && /^file:\/\/\/[A-Za-z]:/.test(url)) {
+        // file:///C:/snapshot/... → /snapshot/...
+        p = url.slice(8); // after file:///C:
+    }
+    else {
+        // file:///snapshot/... → /snapshot/...
+        p = url.slice(7); // after file://
+    }
+    p = decodeURIComponent(p);
+    if (!p.startsWith('/snapshot'))
+        return null;
+    return toCanonical(p);
+}
+exports.fromFileUrl = fromFileUrl;
+// ─────────────────────────────────────────────────────────────────────
+// Snapshot root and app ID extraction
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Get the snapshot root for a given appId in platform-native form.
+ * POSIX: /snapshot/{appId}
+ * Windows: C:\snapshot\{appId}
+ */
+function snapshotRoot(appId) {
+    return toNative(`/snapshot/${appId}`);
+}
+exports.snapshotRoot = snapshotRoot;
+/**
+ * Join a snapshot root with a relative path, returning canonical form.
+ */
+function snapshotJoin(appId, ...segments) {
+    const posix = '/snapshot/' + appId + '/' + segments.join('/');
+    return toCanonical(posix);
+}
+exports.snapshotJoin = snapshotJoin;
+//# sourceMappingURL=snapshot-path.js.map

package/lib-es5/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.platform = void 0;
+exports.platform = {
+    macos: 'darwin',
+    win: 'win32',
+    linux: 'linux',
+};
+//# sourceMappingURL=types.js.map