@veryfront/ext-content-mdx 0.1.1189 → 0.1.1191

package/esm/src/utils/id.js

@@ -0,0 +1,69 @@
+/** ID generation utilities (16-char alphanumeric with optional prefix) */
+import * as dntShim from "../../_dnt.shims.js";
+const ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const MAX_UNBIASED_BYTE = Math.floor(256 / ALPHABET.length) * ALPHABET.length;
+const MAX_ID_SIZE = 1_024;
+function requireIdSize(size) {
+    if (!Number.isSafeInteger(size) || size <= 0 || size > MAX_ID_SIZE) {
+        throw new RangeError(`ID size must be an integer between 1 and ${MAX_ID_SIZE}`);
+    }
+    return size;
+}
+function randomString(length) {
+    requireIdSize(length);
+    let result = "";
+    while (result.length < length) {
+        const remaining = length - result.length;
+        const batchSize = Math.min(65_536, Math.max(32, Math.ceil((remaining * 256) / MAX_UNBIASED_BYTE)));
+        const bytes = new Uint8Array(batchSize);
+        dntShim.crypto.getRandomValues(bytes);
+        // Iterate the allocated batch directly. A project can replace the ambient
+        // typed-array iterator after framework modules load; ID generation must not
+        // execute or depend on that mutable hook.
+        for (let index = 0; index < batchSize; index++) {
+            const byte = bytes[index] ?? 0;
+            if (byte >= MAX_UNBIASED_BYTE)
+                continue;
+            result += ALPHABET[byte % ALPHABET.length];
+            if (result.length === length)
+                break;
+        }
+    }
+    return result;
+}
+/** Generate a secure RFC 4122 version 4 UUID across browser Crypto implementations. */
+export function generateUuid(cryptoImpl = typeof dntShim.crypto !== "undefined"
+    ? dntShim.crypto
+    : undefined) {
+    if (typeof cryptoImpl?.randomUUID === "function") {
+        return cryptoImpl.randomUUID();
+    }
+    if (typeof cryptoImpl?.getRandomValues !== "function") {
+        throw new Error("Web Crypto with getRandomValues is required to generate a secure UUID.");
+    }
+    const bytes = cryptoImpl.getRandomValues(new Uint8Array(16));
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20),
+    ].join("-");
+}
+/** Generate a unique ID with optional prefix (e.g., "msg-a1B2c3D4e5F6g7H8") */
+export function generateId(prefix) {
+    const id = randomString(16);
+    return prefix ? `${prefix}-${id}` : id;
+}
+/** Create an ID generator with fixed prefix and optional configuration */
+export function createIdGenerator(options) {
+    const { prefix, separator = "-", size = 16 } = options;
+    requireIdSize(size);
+    return function generate() {
+        const id = randomString(size);
+        return prefix ? `${prefix}${separator}${id}` : id;
+    };
+}

package/esm/src/utils/import-lockfile.d.ts

@@ -12,7 +12,15 @@ export declare function createEmptyLockfile(): LockfileData;
 /** Compute integrity. */
 export declare function computeIntegrity(content: string): Promise<string>;
 export declare function verifyIntegrity(content: string, integrity: string): Promise<boolean>;
-/** Public API contract for lockfile manager. */
+/**
+ * Public API contract for lockfile manager.
+ *
+ * Reads and updates fail closed with `lockfile-format-mismatch` for an
+ * unsupported format and `lockfile-read-error` for unreadable or malformed
+ * data, so an older Veryfront build cannot overwrite unrecognized lockfile
+ * data. `clear()` is the explicit destructive recovery operation and does not
+ * parse the file before removing it.
+ */
 export interface LockfileManager {
     read(): Promise<LockfileData | null>;
     write(data: LockfileData): Promise<void>;
@@ -23,13 +31,56 @@ export interface LockfileManager {
     flush(): Promise<void>;
 }
 export type FSAdapter = {
+    /**
+     * Authoritative queue identity for adapters that access the same backing
+     * filesystem. Separate adapter objects must share this key to coordinate all
+     * lockfile access, regardless of their optional canonicalization support.
+     */
+    readonly coordinationKey?: string;
     readFile(path: string): Promise<string>;
     writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Atomically replace `to` with the file at `from` (same-directory rename).
+     * When present, lockfile writes stage a temp file and rename it into place,
+     * so a crash mid-write can never leave a truncated lockfile behind.
+     */
+    rename?(from: string, to: string): Promise<void>;
     exists(path: string): Promise<boolean>;
     remove?(path: string): Promise<void>;
+    /**
+     * Resolve an existing project path to its stable backing identity.
+     * Coordination through realPath is per-adapter-instance (or per shared
+     * coordinationKey domain): two separate adapter instances without a shared
+     * coordinationKey never serialize with each other through realPath alone,
+     * even when both implementations agree on the canonical path.
+     */
+    realPath?(path: string): Promise<string>;
 };
 /** Create lockfile manager. */
 export declare function createLockfileManager(projectDir: string, fsAdapter?: FSAdapter): LockfileManager;
+/**
+ * Read a lockfile entry on a build or dev-server hot path.
+ *
+ * A lockfile written by a newer Veryfront build (`lockfile-format-mismatch`)
+ * keeps failing loudly: proceeding around data the running build cannot
+ * understand is exactly the overwrite hazard this module guards against. An
+ * unreadable or malformed lockfile (`lockfile-read-error`) instead degrades to
+ * a cache miss so builds keep working from fresh fetches; a warning naming
+ * the lockfile and the `veryfront lock --clear` remedy is logged once per
+ * manager instead of once per import.
+ */
+export declare function getLockfileEntryForBuild(lockfile: LockfileManager, url: string): Promise<LockfileEntry | null>;
+/**
+ * Persist a lockfile entry from a build or dev-server hot path.
+ *
+ * Mirrors {@link getLockfileEntryForBuild}: when the on-disk lockfile is
+ * unreadable or malformed (`lockfile-read-error`), the file is left untouched
+ * for `veryfront lock --clear` and the entry is simply not recorded, so a
+ * successful refetch still serves the build. Returns whether the entry was
+ * staged; callers should only `flush()` after a `true` result. A newer-format
+ * lockfile (`lockfile-format-mismatch`) keeps failing loudly.
+ */
+export declare function setLockfileEntryForBuild(lockfile: LockfileManager, url: string, entry: LockfileEntry): Promise<boolean>;
 export interface FetchWithLockOptions {
     lockfile: LockfileManager;
     url: string;

package/esm/src/utils/import-lockfile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-lockfile.d.ts","sourceRoot":"","sources":["../../../src/src/utils/import-lockfile.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACxC;AAKD,wBAAgB,mBAAmB,IAAI,YAAY,CAElD;AAED,yBAAyB;AACzB,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGvE;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG1F;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,IAAI,IAAI,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACrC,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAChD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC,CAAC;AAqBF,+BAA+B;AAC/B,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,eAAe,CAkFhG;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA2D/F;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC5B;AAMD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAmB9D;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUlF"}
+{"version":3,"file":"import-lockfile.d.ts","sourceRoot":"","sources":["../../../src/src/utils/import-lockfile.ts"],"names":[],"mappings":"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"}