@makerbi/remodex 1.3.8

package/src/package-version-status.js

@@ -0,0 +1,185 @@
+// FILE: package-version-status.js
+// Purpose: Reads the installed Remodex package version and caches the latest published npm version.
+// Layer: CLI helper
+// Exports: createBridgePackageVersionStatusReader
+// Depends on: https, ../package.json
+
+const https = require("https");
+const { version: installedVersion = "" } = require("../package.json");
+
+const DEFAULT_CACHE_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_EMPTY_CACHE_RETRY_MS = 60 * 1000;
+const DEFAULT_INITIAL_FETCH_WAIT_MS = 250;
+const REMODEX_REGISTRY_URL = "https://registry.npmjs.org/remodex/latest";
+
+function createBridgePackageVersionStatusReader({
+  cacheTtlMs = DEFAULT_CACHE_TTL_MS,
+  emptyCacheRetryMs = DEFAULT_EMPTY_CACHE_RETRY_MS,
+  initialFetchWaitMs = DEFAULT_INITIAL_FETCH_WAIT_MS,
+  registryUrl = REMODEX_REGISTRY_URL,
+  fetchLatestPublishedVersionImpl = fetchLatestPublishedVersion,
+} = {}) {
+  let cachedLatestVersion = "";
+  let lastSuccessfulResolveAt = 0;
+  let lastAttemptedAt = 0;
+  let inFlightPromise = null;
+
+  // Shares one cached lookup across repeated Settings/account refreshes without
+  // holding the local account status path hostage on a slow npm registry call.
+  return async function readBridgePackageVersionStatus() {
+    const now = Date.now();
+    refreshLatestVersionInBackground({
+      now,
+      cacheTtlMs,
+      emptyCacheRetryMs,
+      registryUrl,
+      fetchLatestPublishedVersionImpl,
+      getCachedLatestVersion: () => cachedLatestVersion,
+      getLastSuccessfulResolveAt: () => lastSuccessfulResolveAt,
+      getLastAttemptedAt: () => lastAttemptedAt,
+      getInFlightPromise: () => inFlightPromise,
+      setLastAttemptedAt: (value) => {
+        lastAttemptedAt = value;
+      },
+      setInFlightPromise: (value) => {
+        inFlightPromise = value;
+      },
+      setCachedLatestVersion: (value) => {
+        cachedLatestVersion = value;
+      },
+      setLastSuccessfulResolveAt: (value) => {
+        lastSuccessfulResolveAt = value;
+      },
+    });
+
+    const reportedLatestVersion = await resolveReportedLatestVersion({
+      initialFetchWaitMs,
+      getCachedLatestVersion: () => cachedLatestVersion,
+      getInFlightPromise: () => inFlightPromise,
+    });
+
+    return {
+      bridgeVersion: normalizeVersion(installedVersion) || null,
+      bridgeLatestVersion: reportedLatestVersion || null,
+    };
+  };
+}
+
+// Waits briefly on the very first lookup so fast registry responses can populate
+// Settings immediately, while slow/offline requests still fall back to background refresh.
+async function resolveReportedLatestVersion({
+  initialFetchWaitMs,
+  getCachedLatestVersion,
+  getInFlightPromise,
+}) {
+  const cachedLatestVersion = getCachedLatestVersion();
+  if (cachedLatestVersion) {
+    return cachedLatestVersion;
+  }
+
+  const inFlightPromise = getInFlightPromise();
+  if (!inFlightPromise || initialFetchWaitMs <= 0) {
+    return "";
+  }
+
+  const latestVersion = await Promise.race([
+    inFlightPromise.catch(() => ""),
+    delay(initialFetchWaitMs).then(() => ""),
+  ]);
+
+  return latestVersion || getCachedLatestVersion();
+}
+
+// Refreshes the published version opportunistically while keeping callers fast.
+function refreshLatestVersionInBackground({
+  now,
+  cacheTtlMs,
+  emptyCacheRetryMs,
+  registryUrl,
+  fetchLatestPublishedVersionImpl,
+  getCachedLatestVersion,
+  getLastSuccessfulResolveAt,
+  getLastAttemptedAt,
+  getInFlightPromise,
+  setLastAttemptedAt,
+  setInFlightPromise,
+  setCachedLatestVersion,
+  setLastSuccessfulResolveAt,
+}) {
+  if (getInFlightPromise()) {
+    return;
+  }
+
+  const cachedLatestVersion = getCachedLatestVersion();
+  const isCacheFresh = cachedLatestVersion && now - getLastSuccessfulResolveAt() < cacheTtlMs;
+  const retryWindowMs = cachedLatestVersion ? cacheTtlMs : emptyCacheRetryMs;
+  const recentlyAttempted = now - getLastAttemptedAt() < retryWindowMs;
+
+  if (isCacheFresh || recentlyAttempted) {
+    return;
+  }
+
+  setLastAttemptedAt(now);
+  setInFlightPromise(
+    fetchLatestPublishedVersionImpl(registryUrl)
+      .then((latestVersion) => {
+        setCachedLatestVersion(latestVersion);
+        setLastSuccessfulResolveAt(Date.now());
+        return latestVersion;
+      })
+      .catch(() => getCachedLatestVersion())
+      .finally(() => {
+        setInFlightPromise(null);
+      })
+  );
+}
+
+function fetchLatestPublishedVersion(registryUrl) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(registryUrl, (response) => {
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Unexpected npm registry status: ${response.statusCode || "unknown"}`));
+        return;
+      }
+
+      let raw = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk) => {
+        raw += chunk;
+      });
+      response.on("end", () => {
+        try {
+          const parsed = JSON.parse(raw);
+          const latestVersion = normalizeVersion(parsed?.version);
+          if (!latestVersion) {
+            reject(new Error("npm registry response missing version"));
+            return;
+          }
+          resolve(latestVersion);
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+
+    request.setTimeout(4_000, () => {
+      request.destroy(new Error("npm registry request timed out"));
+    });
+    request.on("error", reject);
+  });
+}
+
+function normalizeVersion(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+function delay(timeoutMs) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, timeoutMs);
+  });
+}
+
+module.exports = {
+  createBridgePackageVersionStatusReader,
+};

package/src/private-defaults.json

@@ -0,0 +1,4 @@
+{
+  "relayUrl": "wss://remodex.vectorvein.com/relay",
+  "pushServiceUrl": ""
+}

package/src/project-handler.js

@@ -0,0 +1,359 @@
+// FILE: project-handler.js
+// Purpose: Serves safe Mac-local project folder discovery and creation requests from the iOS app.
+// Layer: Bridge handler
+// Exports: handleProjectRequest plus testable project filesystem helpers
+// Depends on: fs, os, path
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const DEFAULT_DIRECTORY_LIMIT = 200;
+const DEFAULT_HIDDEN_DIRECTORY_NAMES = new Set(["Library"]);
+
+// ─── ENTRY POINT ─────────────────────────────────────────────
+
+function handleProjectRequest(rawMessage, sendResponse) {
+  let parsed;
+  try {
+    parsed = JSON.parse(rawMessage);
+  } catch {
+    return false;
+  }
+
+  const method = typeof parsed?.method === "string" ? parsed.method.trim() : "";
+  if (!method.startsWith("project/")) {
+    return false;
+  }
+
+  const id = parsed.id;
+  const params = parsed.params || {};
+
+  handleProjectMethod(method, params)
+    .then((result) => {
+      sendResponse(JSON.stringify({ id, result }));
+    })
+    .catch((err) => {
+      const errorCode = err.errorCode || "project_error";
+      const message = err.userMessage || err.message || "Unknown project folder error";
+      sendResponse(
+        JSON.stringify({
+          id,
+          error: {
+            code: -32000,
+            message,
+            data: { errorCode },
+          },
+        })
+      );
+    });
+
+  return true;
+}
+
+async function handleProjectMethod(method, params, options = {}) {
+  switch (method) {
+    case "project/quickLocations":
+      return projectQuickLocations(options);
+    case "project/listDirectory":
+      return projectListDirectory(params, options);
+    case "project/validatePath":
+      return projectValidatePath(params, options);
+    case "project/createDirectory":
+      return projectCreateDirectory(params, options);
+    default:
+      throw projectError("unknown_method", `Unknown project method: ${method}`);
+  }
+}
+
+// ─── Project Methods ─────────────────────────────────────────
+
+async function projectQuickLocations(options = {}) {
+  const homeDir = resolveHomeDir(options);
+  const candidates = [
+    { id: "home", label: "Home", path: homeDir },
+    { id: "developer", label: "Developer", path: path.join(homeDir, "Developer") },
+    { id: "documents", label: "Documents", path: path.join(homeDir, "Documents") },
+    { id: "desktop", label: "Desktop", path: path.join(homeDir, "Desktop") },
+  ];
+
+  const locations = [];
+  for (const candidate of candidates) {
+    const validated = await validateDirectory(candidate.path, options).catch(() => null);
+    if (!validated?.exists || !validated.isDirectory || !validated.isAllowed) {
+      continue;
+    }
+
+    locations.push({
+      id: candidate.id,
+      label: candidate.label,
+      path: validated.path,
+    });
+  }
+
+  return { locations };
+}
+
+async function projectListDirectory(params, options = {}) {
+  const requestedPath = readString(params.path) || resolveHomeDir(options);
+  const directory = await requireUsableDirectory(requestedPath, options);
+  const includeHidden = params.includeHidden === true;
+  const limit = normalizeLimit(params.limit);
+  const entries = await readDirectoryEntries(directory.path, {
+    ...options,
+    includeHidden,
+    limit,
+  });
+
+  return {
+    path: directory.path,
+    parentPath: parentPathWithinAllowedRoots(directory.path, options),
+    entries,
+  };
+}
+
+async function projectValidatePath(params, options = {}) {
+  const requestedPath = readString(params.path);
+  if (!requestedPath) {
+    throw projectError("missing_path", "A folder path is required.");
+  }
+
+  return validateDirectory(requestedPath, options);
+}
+
+async function projectCreateDirectory(params, options = {}) {
+  const parentPath = readString(params.parentPath || params.parent || params.path);
+  const rawName = readString(params.name || params.folderName || params.directoryName);
+  if (!parentPath) {
+    throw projectError("missing_parent_path", "A parent folder path is required.");
+  }
+  if (!rawName) {
+    throw projectError("missing_directory_name", "A new folder name is required.");
+  }
+
+  const parent = await requireUsableDirectory(parentPath, options);
+  const name = normalizeNewDirectoryName(rawName);
+  const targetPath = path.join(parent.path, name);
+  assertPathAllowed(targetPath, options);
+
+  try {
+    await fs.promises.mkdir(targetPath, { recursive: false });
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw projectError("directory_exists", "A folder with that name already exists.");
+    }
+    throw projectError("create_failed", error?.message || "Unable to create that folder.");
+  }
+
+  const created = await requireUsableDirectory(targetPath, options);
+  return {
+    path: created.path,
+    parentPath: parent.path,
+    name: path.basename(created.path),
+  };
+}
+
+// ─── Filesystem Helpers ──────────────────────────────────────
+
+async function readDirectoryEntries(directoryPath, options = {}) {
+  let dirents;
+  try {
+    dirents = await fs.promises.readdir(directoryPath, { withFileTypes: true });
+  } catch (error) {
+    throw projectError("read_failed", error?.message || "Unable to read that folder.");
+  }
+
+  const entries = [];
+  for (const dirent of dirents) {
+    if (!options.includeHidden && isHiddenDirectoryName(dirent.name)) {
+      continue;
+    }
+
+    const childPath = path.join(directoryPath, dirent.name);
+    const directory = await directoryEntryForPath(childPath, dirent, options);
+    if (directory) {
+      entries.push(directory);
+    }
+  }
+
+  return entries
+    .sort((left, right) => left.name.localeCompare(right.name, undefined, { sensitivity: "base" }))
+    .slice(0, options.limit || DEFAULT_DIRECTORY_LIMIT);
+}
+
+async function directoryEntryForPath(candidatePath, dirent, options = {}) {
+  if (!dirent.isDirectory() && !dirent.isSymbolicLink()) {
+    return null;
+  }
+
+  const validation = await validateDirectory(candidatePath, options).catch(() => null);
+  if (!validation?.exists || !validation.isDirectory || !validation.isAllowed) {
+    return null;
+  }
+
+  return {
+    name: dirent.name,
+    path: validation.path,
+    isSymlink: dirent.isSymbolicLink(),
+  };
+}
+
+async function requireUsableDirectory(candidatePath, options = {}) {
+  const validation = await validateDirectory(candidatePath, options);
+  if (!validation.isAllowed) {
+    throw projectError("path_not_allowed", "That folder is outside the allowed local project locations.");
+  }
+  if (!validation.exists) {
+    throw projectError("missing_directory", "That folder does not exist on this Mac.");
+  }
+  if (!validation.isDirectory) {
+    throw projectError("not_directory", "That path is not a folder.");
+  }
+
+  return validation;
+}
+
+async function validateDirectory(candidatePath, options = {}) {
+  const normalizedPath = normalizeCandidatePath(candidatePath, options);
+  const isAllowed = isPathAllowed(normalizedPath, options);
+  if (!isAllowed) {
+    return {
+      path: normalizedPath,
+      exists: false,
+      isDirectory: false,
+      isAllowed: false,
+    };
+  }
+
+  try {
+    const realPath = await fs.promises.realpath(normalizedPath);
+    const stats = await fs.promises.stat(realPath);
+    return {
+      path: realPath,
+      exists: true,
+      isDirectory: stats.isDirectory(),
+      isAllowed: isPathAllowed(realPath, options),
+    };
+  } catch {
+    return {
+      path: normalizedPath,
+      exists: false,
+      isDirectory: false,
+      isAllowed,
+    };
+  }
+}
+
+function parentPathWithinAllowedRoots(candidatePath, options = {}) {
+  const parentPath = path.dirname(candidatePath);
+  if (!parentPath || parentPath === candidatePath) {
+    return null;
+  }
+
+  return isPathAllowed(parentPath, options) ? parentPath : null;
+}
+
+function assertPathAllowed(candidatePath, options = {}) {
+  if (!isPathAllowed(candidatePath, options)) {
+    throw projectError("path_not_allowed", "That folder is outside the allowed local project locations.");
+  }
+}
+
+function isPathAllowed(candidatePath, options = {}) {
+  const normalizedPath = path.resolve(candidatePath);
+  return allowedProjectRoots(options).some((rootPath) => samePathOrDescendant(normalizedPath, rootPath));
+}
+
+function allowedProjectRoots(options = {}) {
+  const roots = Array.isArray(options.allowedRoots) && options.allowedRoots.length
+    ? options.allowedRoots
+    : [resolveHomeDir(options)];
+
+  return [...new Set(roots.flatMap((rootPath) => {
+    const resolvedRoot = path.resolve(rootPath);
+    return [resolvedRoot, realpathSyncIfAvailable(resolvedRoot)].filter(Boolean);
+  }))];
+}
+
+function samePathOrDescendant(candidatePath, rootPath) {
+  const relative = path.relative(rootPath, candidatePath);
+  return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function normalizeCandidatePath(candidatePath, options = {}) {
+  const rawPath = readString(candidatePath);
+  if (!rawPath) {
+    throw projectError("missing_path", "A folder path is required.");
+  }
+
+  if (rawPath === "~" || rawPath.startsWith("~/")) {
+    return path.resolve(resolveHomeDir(options), rawPath.slice(2));
+  }
+
+  if (!path.isAbsolute(rawPath)) {
+    throw projectError("invalid_path", "Use an absolute folder path.");
+  }
+
+  return path.resolve(rawPath);
+}
+
+function isHiddenDirectoryName(name) {
+  return name.startsWith(".") || DEFAULT_HIDDEN_DIRECTORY_NAMES.has(name);
+}
+
+function normalizeNewDirectoryName(rawName) {
+  const name = rawName.trim();
+  if (!name || name === "." || name === "..") {
+    throw projectError("invalid_directory_name", "Use a valid folder name.");
+  }
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+    throw projectError("invalid_directory_name", "Folder names cannot contain path separators.");
+  }
+  if (name.length > 120) {
+    throw projectError("invalid_directory_name", "Use a shorter folder name.");
+  }
+
+  return name;
+}
+
+function normalizeLimit(rawLimit) {
+  const numericLimit = Number(rawLimit);
+  if (!Number.isFinite(numericLimit) || numericLimit <= 0) {
+    return DEFAULT_DIRECTORY_LIMIT;
+  }
+
+  return Math.min(Math.floor(numericLimit), DEFAULT_DIRECTORY_LIMIT);
+}
+
+function resolveHomeDir(options = {}) {
+  return options.homeDir || os.homedir();
+}
+
+function realpathSyncIfAvailable(candidatePath) {
+  try {
+    return fs.realpathSync(candidatePath);
+  } catch {
+    return null;
+  }
+}
+
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function projectError(errorCode, userMessage) {
+  const err = new Error(userMessage);
+  err.errorCode = errorCode;
+  err.userMessage = userMessage;
+  return err;
+}
+
+module.exports = {
+  handleProjectRequest,
+  handleProjectMethod,
+  projectQuickLocations,
+  projectListDirectory,
+  projectValidatePath,
+  projectCreateDirectory,
+  validateDirectory,
+};

package/src/push-notification-completion-dedupe.js

@@ -0,0 +1,147 @@
+// FILE: push-notification-completion-dedupe.js
+// Purpose: Owns duplicate-suppression state for completion pushes emitted by the bridge.
+// Layer: Bridge helper
+// Exports: createPushNotificationCompletionDedupe
+// Depends on: none
+
+const DEFAULT_SENT_DEDUPE_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_STATUS_FALLBACK_TTL_MS = 5_000;
+
+function createPushNotificationCompletionDedupe({
+  now = () => Date.now(),
+  sentDedupeTTLms = DEFAULT_SENT_DEDUPE_TTL_MS,
+  statusFallbackTTLms = DEFAULT_STATUS_FALLBACK_TTL_MS,
+} = {}) {
+  const sentDedupeKeys = new Map();
+  const pendingDedupeKeys = new Set();
+  const recentTurnScopedCompletionsByThread = new Map();
+
+  function clearForNewRun(threadId) {
+    if (!readString(threadId)) {
+      return;
+    }
+
+    recentTurnScopedCompletionsByThread.delete(threadId);
+  }
+
+  // Thread-level terminal events are only a fallback when we have not already sent a turn-scoped completion.
+  function shouldSuppressThreadStatusFallback({ threadId, turnId, result } = {}) {
+    if (readString(turnId)) {
+      return false;
+    }
+
+    pruneRecentTurnScopedCompletions();
+    const previous = recentTurnScopedCompletionsByThread.get(readString(threadId));
+    return previous?.result === result;
+  }
+
+  function hasActiveDedupeKey(dedupeKey) {
+    const normalizedKey = readString(dedupeKey);
+    if (!normalizedKey) {
+      return false;
+    }
+
+    pruneSentDedupeKeys();
+    return sentDedupeKeys.has(normalizedKey) || pendingDedupeKeys.has(normalizedKey);
+  }
+
+  function beginNotification({ dedupeKey, threadId, turnId, result } = {}) {
+    const normalizedKey = readString(dedupeKey);
+    if (!normalizedKey) {
+      return;
+    }
+
+    pendingDedupeKeys.add(normalizedKey);
+    if (readString(turnId)) {
+      rememberTurnScopedCompletion(threadId, result);
+    }
+  }
+
+  function commitNotification({ dedupeKey, threadId, turnId, result } = {}) {
+    const normalizedKey = readString(dedupeKey);
+    if (normalizedKey) {
+      sentDedupeKeys.set(normalizedKey, now());
+      pendingDedupeKeys.delete(normalizedKey);
+    }
+
+    if (readString(turnId)) {
+      rememberTurnScopedCompletion(threadId, result);
+    }
+  }
+
+  function abortNotification({ dedupeKey, threadId, turnId, result } = {}) {
+    const normalizedKey = readString(dedupeKey);
+    if (normalizedKey) {
+      pendingDedupeKeys.delete(normalizedKey);
+    }
+
+    const normalizedThreadId = readString(threadId);
+    if (!readString(turnId) || !normalizedThreadId) {
+      return;
+    }
+
+    const previous = recentTurnScopedCompletionsByThread.get(normalizedThreadId);
+    if (previous?.result === result) {
+      recentTurnScopedCompletionsByThread.delete(normalizedThreadId);
+    }
+  }
+
+  // Exposed for focused tests so we can prove dedupe state stays bounded.
+  function debugState() {
+    pruneSentDedupeKeys();
+    pruneRecentTurnScopedCompletions();
+    return {
+      sentDedupeKeys: sentDedupeKeys.size,
+      pendingDedupeKeys: pendingDedupeKeys.size,
+      recentThreadFallbacks: recentTurnScopedCompletionsByThread.size,
+    };
+  }
+
+  function rememberTurnScopedCompletion(threadId, result) {
+    const normalizedThreadId = readString(threadId);
+    if (!normalizedThreadId) {
+      return;
+    }
+
+    recentTurnScopedCompletionsByThread.set(normalizedThreadId, {
+      result,
+      timestamp: now(),
+    });
+  }
+
+  function pruneSentDedupeKeys() {
+    const cutoff = now() - sentDedupeTTLms;
+    for (const [dedupeKey, timestamp] of sentDedupeKeys.entries()) {
+      if (timestamp < cutoff) {
+        sentDedupeKeys.delete(dedupeKey);
+      }
+    }
+  }
+
+  function pruneRecentTurnScopedCompletions() {
+    const cutoff = now() - statusFallbackTTLms;
+    for (const [threadId, entry] of recentTurnScopedCompletionsByThread.entries()) {
+      if (entry.timestamp < cutoff) {
+        recentTurnScopedCompletionsByThread.delete(threadId);
+      }
+    }
+  }
+
+  return {
+    abortNotification,
+    beginNotification,
+    clearForNewRun,
+    commitNotification,
+    debugState,
+    hasActiveDedupeKey,
+    shouldSuppressThreadStatusFallback,
+  };
+}
+
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+module.exports = {
+  createPushNotificationCompletionDedupe,
+};