@bendyline/docblocks 2.6.1 → 2.7.0

package/dist/chunk-XTNWCNSK.js

@@ -0,0 +1,464 @@
+// src/document/recovery-journal.ts
+var DOCUMENT_RECOVERY_JOURNAL_STORAGE_KEY = "docblocks:document-recovery:v1";
+var DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION = 1;
+var DEFAULT_MAX_ENTRIES = 20;
+var DEFAULT_MAX_STORAGE_BYTES = 2e6;
+var DEFAULT_MAX_RECORD_BYTES = 1e6;
+var DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+var DEFAULT_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
+var MAX_TARGET_KEY_LENGTH = 4096;
+var MAX_STORAGE_KEYS = 1e4;
+var knownStorageKeys = /* @__PURE__ */ new WeakMap();
+var DocumentRecoveryJournal = class _DocumentRecoveryJournal {
+  constructor(storage, options = {}) {
+    this.loadedKeys = [];
+    this.storage = storage;
+    this.baseStorageKey = options.storageKey?.trim() || DOCUMENT_RECOVERY_JOURNAL_STORAGE_KEY;
+    if (options.ownerId !== void 0 && !/^[a-zA-Z0-9-]{1,100}$/.test(options.ownerId)) {
+      throw new TypeError("Invalid recovery journal owner.");
+    }
+    this.options = { ...options, storageKey: this.baseStorageKey };
+    this.storageKey = options.ownerId ? `${this.baseStorageKey}:owner:${options.ownerId}` : this.baseStorageKey;
+    if (storage) {
+      const keys = knownStorageKeys.get(storage) ?? /* @__PURE__ */ new Set();
+      if (!options.ownerId) keys.add(this.storageKey);
+      knownStorageKeys.set(storage, keys);
+    }
+    this.maxEntries = positiveInteger(options.maxEntries, DEFAULT_MAX_ENTRIES);
+    this.maxStorageBytes = positiveInteger(options.maxStorageBytes, DEFAULT_MAX_STORAGE_BYTES);
+    this.maxRecordBytes = Math.min(
+      positiveInteger(options.maxRecordBytes, DEFAULT_MAX_RECORD_BYTES),
+      this.maxStorageBytes
+    );
+    this.maxAgeMs = nonNegativeFinite(options.maxAgeMs, DEFAULT_MAX_AGE_MS);
+    this.maxFutureSkewMs = nonNegativeFinite(options.maxFutureSkewMs, DEFAULT_MAX_FUTURE_SKEW_MS);
+    this.now = options.now ?? Date.now;
+  }
+  /** Isolate writes and acknowledgements from every other live session. */
+  forOwner(ownerId) {
+    return new _DocumentRecoveryJournal(this.storage, { ...this.options, ownerId });
+  }
+  /** Consume only the exact recovered snapshot, never a newer draft from its owner. */
+  acknowledgeRecord(record) {
+    const owner = new _DocumentRecoveryJournal(this.storage, {
+      ...this.options,
+      ownerId: record.ownerId
+    });
+    const records = owner.load(this.now()).records;
+    const current = records.find((candidate) => candidate.targetKey === record.targetKey);
+    if (!current || current.generation !== record.generation || current.revision !== record.revision || current.content !== record.content || current.persistedContent !== record.persistedContent) {
+      return false;
+    }
+    return owner.persistExact(records.filter((candidate) => candidate !== current));
+  }
+  /**
+   * Synchronously persist the latest dirty snapshot for a target.
+   * Storage/quota failures are returned, never thrown into an editor onChange.
+   */
+  write(input) {
+    const timestamp = this.now();
+    if (!isValidWrite(input) || !Number.isFinite(timestamp) || timestamp < 0) {
+      return { status: "rejected", reason: "invalid-record", evicted: 0 };
+    }
+    if (!this.storage) {
+      return { status: "rejected", reason: "storage-unavailable", evicted: 0 };
+    }
+    if (estimatedBytes(input.content) > this.maxRecordBytes || input.persistedContent !== null && estimatedBytes(input.persistedContent) > this.maxRecordBytes) {
+      return { status: "rejected", reason: "record-too-large", evicted: 0 };
+    }
+    const loaded = this.load(timestamp);
+    if (this.options.ownerId && loaded.records.some(
+      (record) => record.targetKey !== input.targetKey && record.generation === input.generation && record.revision === input.revision
+    )) {
+      return { status: "rejected", reason: "invalid-record", evicted: 0 };
+    }
+    const existing = loaded.records.find((record) => record.targetKey === input.targetKey);
+    if (existing) {
+      const ordering = compareGenerationRevision(input, existing);
+      if (ordering < 0) return { status: "ignored-stale", evicted: 0 };
+      if (ordering === 0) {
+        if (existing.content === input.content && existing.persistedContent === input.persistedContent) {
+          return { status: "unchanged", evicted: 0 };
+        }
+        return { status: "rejected", reason: "invalid-record", evicted: 0 };
+      }
+    }
+    const candidate = {
+      targetKey: input.targetKey,
+      generation: input.generation,
+      revision: input.revision,
+      content: input.content,
+      persistedContent: input.persistedContent,
+      createdAt: existing?.createdAt ?? timestamp,
+      updatedAt: timestamp
+    };
+    if (estimatedBytes(JSON.stringify(candidate)) > this.maxRecordBytes) {
+      return { status: "rejected", reason: "record-too-large", evicted: 0 };
+    }
+    if (estimatedBytes(serializeEnvelope([candidate])) > this.maxStorageBytes) {
+      return { status: "rejected", reason: "record-too-large", evicted: 0 };
+    }
+    const next = loaded.records.filter((record) => record.targetKey !== input.targetKey);
+    next.push(candidate);
+    const persisted = this.persistBounded(next, input.targetKey);
+    if (!persisted.stored) {
+      return {
+        status: "rejected",
+        reason: persisted.reason ?? "quota-exceeded",
+        evicted: persisted.evicted
+      };
+    }
+    return { status: "stored", evicted: persisted.evicted + this.pruneOwners(input.targetKey) };
+  }
+  pruneOwners(protectedTarget) {
+    if (!this.options.ownerId) return 0;
+    const records = this.loadAll().sort(compareNewestFirst);
+    let bytes = estimatedBytes(JSON.stringify(records));
+    let evicted = 0;
+    for (let index = records.length - 1; index >= 0 && (records.length > this.maxEntries || bytes > this.maxStorageBytes); index--) {
+      const record = records[index];
+      if (record.ownerId === this.options.ownerId && record.targetKey === protectedTarget) continue;
+      if (!this.acknowledgeRecord(record)) continue;
+      bytes -= estimatedBytes(JSON.stringify(record));
+      records.splice(index, 1);
+      evicted++;
+    }
+    return evicted;
+  }
+  /** Return the recoverable snapshot for one target, if present and valid. */
+  lookup(targetKey, generation) {
+    if (!isValidTargetKey(targetKey) || !isOptionalGeneration(generation)) return null;
+    const record = this.list(targetKey).find(
+      (candidate) => candidate.targetKey === targetKey && (generation === void 0 || candidate.generation === generation)
+    );
+    return record ? cloneRecord(record) : null;
+  }
+  /** List valid records, newest first. Optionally restrict to one target. */
+  list(targetKey) {
+    if (targetKey !== void 0 && !isValidTargetKey(targetKey)) return [];
+    return this.loadAll().filter((record) => targetKey === void 0 || record.targetKey === targetKey).sort(compareNewestFirst).map(cloneRecord);
+  }
+  loadAll() {
+    if (!this.storage) return [];
+    const prefix = `${this.baseStorageKey}:owner:`;
+    const keys = this.storageKeys();
+    const owners = /* @__PURE__ */ new Set([void 0, this.options.ownerId]);
+    for (const key of keys) {
+      if (!key.startsWith(prefix)) continue;
+      const ownerId = key.slice(prefix.length).split(":")[0];
+      if (/^[a-zA-Z0-9-]{1,100}$/.test(ownerId)) owners.add(ownerId);
+    }
+    const records = [];
+    for (const ownerId of owners) {
+      const journal = new _DocumentRecoveryJournal(this.storage, { ...this.options, ownerId });
+      for (const record of journal.load(this.now()).records) {
+        records.push({ ...record, ...ownerId ? { ownerId } : {} });
+      }
+    }
+    return records;
+  }
+  storageKeys() {
+    if (!this.storage) return [];
+    const keys = /* @__PURE__ */ new Set([this.baseStorageKey, ...knownStorageKeys.get(this.storage) ?? []]);
+    try {
+      const count = Math.min(this.storage.length ?? 0, MAX_STORAGE_KEYS);
+      for (let index = 0; index < count; index++) {
+        const key = this.storage.key?.(index);
+        if (key?.startsWith(`${this.baseStorageKey}:owner:`)) keys.add(key);
+      }
+    } catch {
+    }
+    return [...keys].slice(0, MAX_STORAGE_KEYS);
+  }
+  /**
+   * Clear a record only when the same generation has durably acknowledged at
+   * least the journaled revision. A stale acknowledgement cannot erase a newer
+   * crash-recovery snapshot.
+   */
+  acknowledge(input) {
+    if (!isValidAcknowledgement(input) || !this.storage) return false;
+    const records = this.load(this.now()).records;
+    const record = records.find((candidate) => candidate.targetKey === input.targetKey);
+    if (!record || record.generation !== input.generation || record.revision > input.persistedRevision) {
+      return false;
+    }
+    return this.persistExact(records.filter((candidate) => candidate !== record));
+  }
+  /** Explicitly discard recovery data after a user or lifecycle decision. */
+  discard(targetKey, generation) {
+    if (!isValidTargetKey(targetKey) || !isOptionalGeneration(generation) || !this.storage) {
+      return false;
+    }
+    const records = this.load(this.now()).records;
+    const next = records.filter(
+      (record) => record.targetKey !== targetKey || generation !== void 0 && record.generation !== generation
+    );
+    if (next.length === records.length) return false;
+    return this.persistExact(next);
+  }
+  load(timestamp) {
+    if (!this.storage) return { records: [], needsRepair: false };
+    let raw;
+    let readNeedsRepair = false;
+    try {
+      if (this.options.ownerId) {
+        this.loadedKeys = this.storageKeys().filter((key) => key.startsWith(`${this.storageKey}:`));
+        const records2 = [];
+        for (const key of this.loadedKeys) {
+          const item = this.storage.getItem(key);
+          if (item === null || estimatedBytes(item) > this.maxRecordBytes) {
+            readNeedsRepair = true;
+            continue;
+          }
+          try {
+            const record = JSON.parse(item);
+            if (isObject(record) && key === `${this.storageKey}:${record.generation}:${record.revision}`)
+              records2.push(record);
+            else readNeedsRepair = true;
+          } catch {
+            readNeedsRepair = true;
+          }
+        }
+        raw = JSON.stringify({ schemaVersion: DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION, records: records2 });
+      } else {
+        raw = this.storage.getItem(this.storageKey);
+      }
+    } catch {
+      return { records: [], needsRepair: false };
+    }
+    if (raw === null) return { records: [], needsRepair: false };
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      this.tryRemove();
+      return { records: [], needsRepair: true };
+    }
+    if (!isEnvelope(parsed)) {
+      this.tryRemove();
+      return { records: [], needsRepair: true };
+    }
+    const byTarget = /* @__PURE__ */ new Map();
+    let needsRepair = readNeedsRepair || estimatedBytes(raw) > this.maxStorageBytes;
+    for (const candidate of parsed.records) {
+      if (!isValidStoredRecord(candidate, timestamp, this.maxAgeMs, this.maxFutureSkewMs)) {
+        needsRepair = true;
+        continue;
+      }
+      if (estimatedBytes(JSON.stringify(candidate)) > this.maxRecordBytes) {
+        needsRepair = true;
+        continue;
+      }
+      const current = byTarget.get(candidate.targetKey);
+      if (!current || compareStoredRecords(candidate, current) > 0) {
+        if (current) needsRepair = true;
+        byTarget.set(candidate.targetKey, cloneRecord(candidate));
+      } else {
+        needsRepair = true;
+      }
+    }
+    const records = [...byTarget.values()].sort(compareNewestFirst);
+    while (records.length > this.maxEntries) {
+      records.pop();
+      needsRepair = true;
+    }
+    while (records.length > 0 && estimatedBytes(serializeEnvelope(records)) > this.maxStorageBytes) {
+      records.pop();
+      needsRepair = true;
+    }
+    if (needsRepair) {
+      this.persistBounded(records);
+    }
+    return { records, needsRepair };
+  }
+  persistBounded(records, protectedTarget) {
+    if (!this.storage) {
+      return { stored: false, evicted: 0, reason: "storage-unavailable" };
+    }
+    const next = [...records].sort(compareNewestFirst);
+    let evicted = 0;
+    while (next.length > this.maxEntries) {
+      if (!evictOldest(next, protectedTarget)) break;
+      evicted += 1;
+    }
+    let serialized = serializeEnvelope(next);
+    while (estimatedBytes(serialized) > this.maxStorageBytes) {
+      if (!evictOldest(next, protectedTarget)) {
+        return { stored: false, evicted, reason: "quota-exceeded" };
+      }
+      evicted += 1;
+      serialized = serializeEnvelope(next);
+    }
+    for (; ; ) {
+      try {
+        if (this.options.ownerId) this.persistOwned(next, protectedTarget);
+        else this.storage.setItem(this.storageKey, serialized);
+        return { stored: true, evicted };
+      } catch {
+        if (!evictOldest(next, protectedTarget)) {
+          return { stored: false, evicted, reason: "quota-exceeded" };
+        }
+        evicted += 1;
+        serialized = serializeEnvelope(next);
+      }
+    }
+  }
+  persistExact(records) {
+    if (!this.storage) return false;
+    if (this.options.ownerId) {
+      try {
+        this.persistOwned(records);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    if (records.length === 0) {
+      try {
+        this.storage.removeItem(this.storageKey);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    try {
+      this.storage.setItem(this.storageKey, serializeEnvelope(records));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Each owner/revision is immutable and has its own key. A recovering window
+   * may remove that exact key without racing a live owner's newer write.
+   * Only explicit writes create records; cleanup never recreates a saved draft.
+   */
+  persistOwned(records, writtenTarget) {
+    if (!this.storage) return;
+    const keyFor = (record) => `${this.storageKey}:${record.generation}:${record.revision}`;
+    if (writtenTarget !== void 0) {
+      const record = records.find((entry) => entry.targetKey === writtenTarget);
+      if (record) {
+        const key = keyFor(record);
+        this.storage.setItem(key, JSON.stringify(record));
+        knownStorageKeys.get(this.storage)?.add(key);
+      }
+    }
+    const retained = new Set(records.map(keyFor));
+    for (const key of this.loadedKeys) {
+      if (retained.has(key)) continue;
+      this.storage.removeItem(key);
+      knownStorageKeys.get(this.storage)?.delete(key);
+    }
+  }
+  tryRemove() {
+    try {
+      this.storage?.removeItem(this.storageKey);
+    } catch {
+    }
+  }
+};
+function getDefaultDocumentRecoveryStorage() {
+  try {
+    const candidate = Reflect.get(globalThis, "localStorage");
+    if (!isStorage(candidate)) return null;
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+function serializeEnvelope(records) {
+  const envelope = {
+    schemaVersion: DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION,
+    records
+  };
+  return JSON.stringify(envelope);
+}
+function estimatedBytes(value) {
+  return value.length * 2;
+}
+function positiveInteger(value, fallback) {
+  return Number.isSafeInteger(value) && (value ?? 0) > 0 ? value : fallback;
+}
+function nonNegativeFinite(value, fallback) {
+  return Number.isFinite(value) && (value ?? -1) >= 0 ? value : fallback;
+}
+function isEnvelope(value) {
+  if (!isObject(value)) return false;
+  return Object.keys(value).every((key) => key === "schemaVersion" || key === "records") && value.schemaVersion === DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION && Array.isArray(value.records);
+}
+function isValidStoredRecord(value, timestamp, maxAgeMs, maxFutureSkewMs) {
+  if (!isObject(value)) return false;
+  const fields = [
+    "targetKey",
+    "generation",
+    "revision",
+    "content",
+    "persistedContent",
+    "createdAt",
+    "updatedAt"
+  ];
+  if (Object.keys(value).some((key) => !fields.includes(key)) || !isValidTargetKey(value.targetKey) || !isNonNegativeSafeInteger(value.generation) || !isNonNegativeSafeInteger(value.revision) || typeof value.content !== "string" || value.persistedContent !== null && typeof value.persistedContent !== "string" || !isNonNegativeFiniteNumber(value.createdAt) || !isNonNegativeFiniteNumber(value.updatedAt) || value.createdAt > value.updatedAt) {
+    return false;
+  }
+  if (!Number.isFinite(timestamp) || timestamp < 0) return false;
+  if (value.updatedAt > timestamp + maxFutureSkewMs) return false;
+  return timestamp - value.updatedAt <= maxAgeMs;
+}
+function isValidWrite(value) {
+  return isValidTargetKey(value.targetKey) && isNonNegativeSafeInteger(value.generation) && isNonNegativeSafeInteger(value.revision) && typeof value.content === "string" && (value.persistedContent === null || typeof value.persistedContent === "string");
+}
+function isValidAcknowledgement(value) {
+  return isValidTargetKey(value.targetKey) && isNonNegativeSafeInteger(value.generation) && isNonNegativeSafeInteger(value.persistedRevision);
+}
+function isValidTargetKey(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= MAX_TARGET_KEY_LENGTH;
+}
+function isOptionalGeneration(value) {
+  return value === void 0 || isNonNegativeSafeInteger(value);
+}
+function isNonNegativeSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isNonNegativeFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isStorage(value) {
+  if (!isObject(value)) return false;
+  return typeof value.getItem === "function" && typeof value.setItem === "function" && typeof value.removeItem === "function";
+}
+function compareGenerationRevision(left, right) {
+  if (left.generation !== right.generation) return left.generation - right.generation;
+  return left.revision - right.revision;
+}
+function compareStoredRecords(left, right) {
+  return compareGenerationRevision(left, right) || left.updatedAt - right.updatedAt;
+}
+function compareNewestFirst(left, right) {
+  return right.updatedAt - left.updatedAt || right.revision - left.revision;
+}
+function cloneRecord(record) {
+  return { ...record };
+}
+function evictOldest(records, protectedTarget) {
+  let oldestIndex = -1;
+  for (let index = 0; index < records.length; index += 1) {
+    if (records[index].targetKey === protectedTarget) continue;
+    if (oldestIndex < 0 || compareNewestFirst(records[index], records[oldestIndex]) > 0) {
+      oldestIndex = index;
+    }
+  }
+  if (oldestIndex < 0) return false;
+  records.splice(oldestIndex, 1);
+  return true;
+}
+
+export {
+  DOCUMENT_RECOVERY_JOURNAL_STORAGE_KEY,
+  DOCUMENT_RECOVERY_JOURNAL_SCHEMA_VERSION,
+  DocumentRecoveryJournal,
+  getDefaultDocumentRecoveryStorage
+};

package/dist/chunk-YHSFRPBS.js

@@ -0,0 +1,42 @@
+// src/filesystem/workspace-entry-rules.ts
+var TOOL_MANAGED_FOLDER_NAMES = /* @__PURE__ */ new Set([
+  "node_modules",
+  "bower_components",
+  "__pycache__"
+]);
+function isIgnoredWorkspaceEntryName(name) {
+  return name.startsWith(".") || TOOL_MANAGED_FOLDER_NAMES.has(name.toLowerCase());
+}
+var MARKDOWN_FILE_EXTENSIONS = Object.freeze([
+  ".md",
+  ".markdown",
+  ".mdown"
+]);
+function isMarkdownFileName(name) {
+  const lower = name.toLowerCase();
+  return MARKDOWN_FILE_EXTENSIONS.some(
+    (extension) => lower.length > extension.length && lower.endsWith(extension)
+  );
+}
+function isCompanionDirectoryName(name) {
+  return name.endsWith("_files");
+}
+var SQUISQ_RUNTIME_DIRECTORY_NAME = "_squisq";
+function isBrowsableWorkspaceEntry(name, kind) {
+  if (isIgnoredWorkspaceEntryName(name)) return false;
+  return kind === "file" || !isCompanionDirectoryName(name);
+}
+function isDiscoverableWorkspaceEntry(name, kind) {
+  if (!isBrowsableWorkspaceEntry(name, kind)) return false;
+  return kind === "file" || name !== SQUISQ_RUNTIME_DIRECTORY_NAME;
+}
+
+export {
+  isIgnoredWorkspaceEntryName,
+  MARKDOWN_FILE_EXTENSIONS,
+  isMarkdownFileName,
+  isCompanionDirectoryName,
+  SQUISQ_RUNTIME_DIRECTORY_NAME,
+  isBrowsableWorkspaceEntry,
+  isDiscoverableWorkspaceEntry
+};