simplemdg-dev-cli 2.5.0 → 2.6.0

package/src/core/cache/smart-cache-manager.ts

@@ -0,0 +1,169 @@
+import { emitCacheEvent } from "./smart-cache-events";
+import { readEntry, writeEntry } from "./smart-cache-store";
+import type {
+  TCacheStatus,
+  TSmartCacheEntry,
+  TSmartCacheReadOptions,
+  TSmartCacheResult,
+} from "./smart-cache.types";
+
+const CACHE_VERSION = 1;
+
+/** In-memory registry so concurrent callers share a single network refresh. */
+const pendingRefreshes = new Map<string, Promise<unknown>>();
+
+function fullKey(namespace: string, key: string): string {
+  return `${namespace}::${key}`;
+}
+
+export function computeCacheStatus(entry: Pick<TSmartCacheEntry<unknown>, "updatedAt" | "ttlMs">, now = Date.now()): TCacheStatus {
+  if (!Number.isFinite(entry.ttlMs)) {
+    return "fresh";
+  }
+
+  const age = now - new Date(entry.updatedAt).getTime();
+
+  if (age < entry.ttlMs) {
+    return "fresh";
+  }
+
+  if (age < entry.ttlMs * 8) {
+    return "stale";
+  }
+
+  return "expired";
+}
+
+function buildEntry<TData>(namespace: string, key: string, data: TData, ttlMs: number, previous?: TSmartCacheEntry<TData>): TSmartCacheEntry<TData> {
+  const now = new Date().toISOString();
+  return {
+    key,
+    data,
+    createdAt: previous?.createdAt ?? now,
+    updatedAt: now,
+    expiresAt: Number.isFinite(ttlMs) ? new Date(Date.now() + ttlMs).toISOString() : undefined,
+    source: "network",
+    status: "fresh",
+    refreshState: "success",
+    lastRefreshStartedAt: previous?.lastRefreshStartedAt,
+    lastRefreshFinishedAt: now,
+    lastRefreshError: undefined,
+    ttlMs,
+    version: CACHE_VERSION,
+  };
+}
+
+/**
+ * Start (or join) a deduplicated background refresh for a cache key. Resolves
+ * with the fresh data; on failure the old cache entry is preserved and the
+ * error is recorded in metadata.
+ */
+export function refreshCache<TData>(options: { namespace: string; key: string; ttlMs: number; resource?: string; fetcher: () => Promise<TData> }): Promise<TData> {
+  const id = fullKey(options.namespace, options.key);
+  const existing = pendingRefreshes.get(id);
+
+  if (existing) {
+    return existing as Promise<TData>;
+  }
+
+  const resource = options.resource ?? options.namespace;
+  emitCacheEvent({ type: "cache-refresh-started", key: options.key, resource });
+
+  const promise = (async (): Promise<TData> => {
+    try {
+      const data = await options.fetcher();
+      const previous = await readEntry<TData>(options.namespace, options.key);
+      const entry = buildEntry(options.namespace, options.key, data, options.ttlMs, previous);
+      await writeEntry(options.namespace, options.key, entry);
+      emitCacheEvent({ type: "cache-refresh-success", key: options.key, resource, updatedAt: entry.updatedAt });
+      return data;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const previous = await readEntry<TData>(options.namespace, options.key);
+      if (previous) {
+        previous.refreshState = "failed";
+        previous.lastRefreshFinishedAt = new Date().toISOString();
+        previous.lastRefreshError = message;
+        await writeEntry(options.namespace, options.key, previous).catch(() => undefined);
+      }
+      emitCacheEvent({ type: "cache-refresh-failed", key: options.key, resource, error: message });
+      throw error;
+    } finally {
+      pendingRefreshes.delete(id);
+    }
+  })();
+
+  pendingRefreshes.set(id, promise);
+  return promise;
+}
+
+/**
+ * Smart cache read: returns cached data immediately under stale-while-revalidate
+ * (the default) and refreshes in the background, or follows the requested mode.
+ */
+export async function smartRead<TData>(options: TSmartCacheReadOptions<TData>): Promise<TSmartCacheResult<TData>> {
+  const mode = options.mode ?? "stale-while-revalidate";
+  const entry = await readEntry<TData>(options.namespace, options.key);
+  const status = entry ? computeCacheStatus(entry) : "missing";
+
+  const networkOnce = async (): Promise<TSmartCacheResult<TData>> => {
+    const data = await refreshCache({ namespace: options.namespace, key: options.key, ttlMs: options.ttlMs, resource: options.namespace, fetcher: options.fetcher });
+    return { data, fromCache: false, cacheStatus: "fresh", isRefreshing: false, updatedAt: new Date().toISOString() };
+  };
+
+  if (mode === "network-only") {
+    return networkOnce();
+  }
+
+  if (mode === "cache-only") {
+    if (!entry) {
+      throw new Error(`No cached data for ${options.namespace}::${options.key}`);
+    }
+    return { data: entry.data, fromCache: true, cacheStatus: status === "missing" ? "expired" : status, isRefreshing: false, updatedAt: entry.updatedAt };
+  }
+
+  if (mode === "network-first") {
+    try {
+      return await networkOnce();
+    } catch (error) {
+      if (entry) {
+        return { data: entry.data, fromCache: true, cacheStatus: status === "missing" ? "expired" : status, isRefreshing: false, updatedAt: entry.updatedAt };
+      }
+      throw error;
+    }
+  }
+
+  if (mode === "cache-first") {
+    if (entry) {
+      return { data: entry.data, fromCache: true, cacheStatus: status === "missing" ? "expired" : status, isRefreshing: false, updatedAt: entry.updatedAt };
+    }
+    return networkOnce();
+  }
+
+  // stale-while-revalidate (default)
+  if (!entry) {
+    return networkOnce();
+  }
+
+  const shouldRevalidate = options.revalidateWhenFresh !== false || status !== "fresh";
+  let refreshPromise: Promise<TData> | undefined;
+
+  if (shouldRevalidate) {
+    refreshPromise = refreshCache({ namespace: options.namespace, key: options.key, ttlMs: options.ttlMs, resource: options.namespace, fetcher: options.fetcher });
+    // Avoid an unhandled rejection if the caller never awaits it.
+    refreshPromise.catch(() => undefined);
+  }
+
+  return {
+    data: entry.data,
+    fromCache: true,
+    cacheStatus: status === "missing" ? "expired" : status,
+    isRefreshing: Boolean(refreshPromise),
+    updatedAt: entry.updatedAt,
+    refreshPromise,
+  };
+}
+
+export function isRefreshPending(namespace: string, key: string): boolean {
+  return pendingRefreshes.has(fullKey(namespace, key));
+}

package/src/core/cache/smart-cache-store.ts

@@ -0,0 +1,83 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import type { TNamespaceStat, TSmartCacheEntry } from "./smart-cache.types";
+
+const CACHE_DIRECTORY = path.join(os.homedir(), ".simplemdg", "cache");
+
+type TNamespaceFile = Record<string, TSmartCacheEntry<unknown>>;
+
+function namespaceFilePath(namespace: string): string {
+  return path.join(CACHE_DIRECTORY, `${namespace}.json`);
+}
+
+export function getCacheDirectory(): string {
+  return CACHE_DIRECTORY;
+}
+
+async function readNamespaceFile(namespace: string): Promise<TNamespaceFile> {
+  const filePath = namespaceFilePath(namespace);
+
+  if (!(await fs.pathExists(filePath))) {
+    return {};
+  }
+
+  const parsed = await fs.readJson(filePath).catch(() => ({})) as TNamespaceFile;
+  return parsed && typeof parsed === "object" ? parsed : {};
+}
+
+async function writeNamespaceFile(namespace: string, file: TNamespaceFile): Promise<void> {
+  await fs.ensureDir(CACHE_DIRECTORY);
+  await fs.writeJson(namespaceFilePath(namespace), file, { spaces: 2 });
+}
+
+export async function readEntry<TData>(namespace: string, key: string): Promise<TSmartCacheEntry<TData> | undefined> {
+  const file = await readNamespaceFile(namespace);
+  return file[key] as TSmartCacheEntry<TData> | undefined;
+}
+
+export async function readAllEntries<TData>(namespace: string): Promise<Record<string, TSmartCacheEntry<TData>>> {
+  return await readNamespaceFile(namespace) as Record<string, TSmartCacheEntry<TData>>;
+}
+
+export async function writeEntry<TData>(namespace: string, key: string, entry: TSmartCacheEntry<TData>): Promise<void> {
+  const file = await readNamespaceFile(namespace);
+  file[key] = entry as TSmartCacheEntry<unknown>;
+  await writeNamespaceFile(namespace, file);
+}
+
+export async function removeEntry(namespace: string, key: string): Promise<boolean> {
+  const file = await readNamespaceFile(namespace);
+
+  if (!(key in file)) {
+    return false;
+  }
+
+  delete file[key];
+  await writeNamespaceFile(namespace, file);
+  return true;
+}
+
+export async function clearNamespace(namespace: string): Promise<void> {
+  await fs.remove(namespaceFilePath(namespace)).catch(() => undefined);
+}
+
+export async function statNamespace(namespace: string): Promise<TNamespaceStat> {
+  const filePath = namespaceFilePath(namespace);
+
+  if (!(await fs.pathExists(filePath))) {
+    return { namespace, count: 0, exists: false };
+  }
+
+  const file = await readNamespaceFile(namespace);
+  const entries = Object.values(file);
+  let lastUpdatedAt: string | undefined;
+
+  for (const entry of entries) {
+    if (!lastUpdatedAt || entry.updatedAt > lastUpdatedAt) {
+      lastUpdatedAt = entry.updatedAt;
+    }
+  }
+
+  return { namespace, count: entries.length, lastUpdatedAt, exists: true };
+}

package/src/core/cache/smart-cache.ts

@@ -0,0 +1,97 @@
+export * from "./smart-cache.types";
+export { smartRead, refreshCache, computeCacheStatus, isRefreshPending } from "./smart-cache-manager";
+export { onCacheEvent, emitCacheEvent } from "./smart-cache-events";
+export {
+  clearNamespace,
+  statNamespace,
+  removeEntry,
+  readEntry,
+  writeEntry,
+  getCacheDirectory,
+} from "./smart-cache-store";
+
+/** Known cache namespaces with human labels (also drives `smdg cache status`). */
+export const CACHE_NAMESPACES: Record<string, string> = {
+  "cf-regions": "CF regions",
+  "cf-targets": "CF targets",
+  "cf-orgs": "CF orgs",
+  "cf-spaces": "CF spaces",
+  "cf-apps": "CF apps",
+  "cf-env": "CF env (parsed, non-secret)",
+  "db-import-candidates": "DB import candidates",
+  "db-metadata": "DB metadata",
+  "gitlab-groups": "GitLab groups",
+  "gitlab-projects": "GitLab projects",
+  "cf-recent-targets": "CF recent targets",
+  "cf-favorite-targets": "CF favorite targets",
+};
+
+/** Namespace groups for `smdg cache clear|refresh <scope>`. */
+export const CACHE_SCOPES: Record<string, string[]> = {
+  cf: ["cf-regions", "cf-targets", "cf-orgs", "cf-spaces", "cf-apps", "cf-env"],
+  gitlab: ["gitlab-groups", "gitlab-projects"],
+  db: ["db-import-candidates", "db-metadata"],
+  target: ["cf-targets", "cf-recent-targets", "cf-favorite-targets"],
+  all: Object.keys(CACHE_NAMESPACES),
+};
+
+function sanitize(value: string | undefined): string {
+  return (value ?? "").trim().replace(/::/g, ":") || "_";
+}
+
+export function buildCfRegionKey(region: string): string {
+  return sanitize(region);
+}
+
+export function buildCfOrgKey(region: string): string {
+  return sanitize(region);
+}
+
+export function buildCfSpaceKey(region: string, org: string): string {
+  return `${sanitize(region)}::${sanitize(org)}`;
+}
+
+export function buildCfTargetKey(region: string, org: string, space: string): string {
+  return `${sanitize(region)}::${sanitize(org)}::${sanitize(space)}`;
+}
+
+export function buildCfAppsKey(region: string, org: string, space: string): string {
+  return buildCfTargetKey(region, org, space);
+}
+
+export function buildCfEnvKey(region: string, org: string, space: string, appName: string): string {
+  return `${buildCfTargetKey(region, org, space)}::${sanitize(appName)}`;
+}
+
+export function buildDbImportCandidatesKey(region: string, org: string, space: string, appName: string): string {
+  return buildCfEnvKey(region, org, space, appName);
+}
+
+export function buildGitLabGroupsKey(baseUrl: string, userId?: string | number): string {
+  return `${sanitize(baseUrl)}::${sanitize(userId === undefined ? "" : String(userId))}`;
+}
+
+export function buildGitLabProjectsKey(baseUrl: string, groupId: string | number): string {
+  return `${sanitize(baseUrl)}::${sanitize(String(groupId))}`;
+}
+
+export function formatRelativeTime(iso: string | undefined): string {
+  if (!iso) {
+    return "never";
+  }
+
+  const deltaMs = Date.now() - new Date(iso).getTime();
+
+  if (deltaMs < 0) {
+    return "just now";
+  }
+
+  const seconds = Math.floor(deltaMs / 1000);
+  if (seconds < 45) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  const days = Math.floor(hours / 24);
+  return `${days} day${days === 1 ? "" : "s"} ago`;
+}

package/src/core/cache/smart-cache.types.ts

@@ -0,0 +1,79 @@
+export type TCacheReadMode =
+  | "cache-first"
+  | "network-first"
+  | "cache-only"
+  | "network-only"
+  | "stale-while-revalidate";
+
+export type TCacheStatus = "fresh" | "stale" | "expired";
+
+export type TRefreshState = "idle" | "refreshing" | "success" | "failed";
+
+export type TSmartCacheEntry<TData> = {
+  key: string;
+  data: TData;
+  createdAt: string;
+  updatedAt: string;
+  expiresAt?: string;
+  source: "cache" | "network";
+  status: TCacheStatus;
+  refreshState?: TRefreshState;
+  lastRefreshStartedAt?: string;
+  lastRefreshFinishedAt?: string;
+  lastRefreshError?: string;
+  ttlMs: number;
+  version: number;
+};
+
+export type TSmartCacheResult<TData> = {
+  data: TData;
+  fromCache: boolean;
+  cacheStatus: TCacheStatus | "missing";
+  isRefreshing: boolean;
+  updatedAt?: string;
+  refreshPromise?: Promise<TData>;
+};
+
+export type TSmartCacheReadOptions<TData> = {
+  namespace: string;
+  key: string;
+  ttlMs: number;
+  mode?: TCacheReadMode;
+  fetcher: () => Promise<TData>;
+  /** Revalidate in the background even when the cached entry is still fresh. */
+  revalidateWhenFresh?: boolean;
+};
+
+export type TCacheEventType =
+  | "cache-refresh-started"
+  | "cache-refresh-success"
+  | "cache-refresh-failed";
+
+export type TCacheEvent = {
+  type: TCacheEventType;
+  key: string;
+  resource: string;
+  updatedAt?: string;
+  error?: string;
+};
+
+export type TNamespaceStat = {
+  namespace: string;
+  count: number;
+  lastUpdatedAt?: string;
+  exists: boolean;
+};
+
+/** Default TTLs (ms). BTP/GitLab structures rarely change second-to-second. */
+export const DEFAULT_CACHE_TTL = {
+  cfRegions: 7 * 24 * 60 * 60 * 1000,
+  cfOrgs: 6 * 60 * 60 * 1000,
+  cfSpaces: 6 * 60 * 60 * 1000,
+  cfApps: 10 * 60 * 1000,
+  cfEnv: 5 * 60 * 1000,
+  dbImportCandidates: 10 * 60 * 1000,
+  gitlabGroups: 6 * 60 * 60 * 1000,
+  gitlabProjects: 30 * 60 * 1000,
+  dbMetadata: 10 * 60 * 1000,
+  dbConnections: Number.POSITIVE_INFINITY,
+} as const;

package/src/core/cf/cf-target-cache.ts

@@ -0,0 +1,61 @@
+import { readAllEntries, readEntry, removeEntry, writeEntry } from "../cache/smart-cache-store";
+import { cfTargetKey } from "./cf-target.types";
+import type { TCfTarget } from "./cf-target.types";
+import type { TSmartCacheEntry } from "../cache/smart-cache.types";
+
+const FAVORITES_NAMESPACE = "cf-favorite-targets";
+const RECENT_NAMESPACE = "cf-recent-targets";
+const MAX_RECENT = 20;
+
+function toEntry(target: TCfTarget): TSmartCacheEntry<TCfTarget> {
+  const now = new Date().toISOString();
+  return {
+    key: cfTargetKey(target),
+    data: target,
+    createdAt: now,
+    updatedAt: target.lastUsedAt ?? now,
+    source: "cache",
+    status: "fresh",
+    ttlMs: Number.POSITIVE_INFINITY,
+    version: 1,
+  };
+}
+
+export async function listFavoriteTargets(): Promise<TCfTarget[]> {
+  const entries = await readAllEntries<TCfTarget>(FAVORITES_NAMESPACE);
+  return Object.values(entries).map((entry) => ({ ...entry.data, isFavorite: true }));
+}
+
+export async function isFavoriteTarget(target: TCfTarget): Promise<boolean> {
+  return Boolean(await readEntry<TCfTarget>(FAVORITES_NAMESPACE, cfTargetKey(target)));
+}
+
+export async function addFavoriteTarget(target: TCfTarget): Promise<void> {
+  await writeEntry(FAVORITES_NAMESPACE, cfTargetKey(target), toEntry({ ...target, isFavorite: true }));
+}
+
+export async function removeFavoriteTarget(target: TCfTarget): Promise<void> {
+  await removeEntry(FAVORITES_NAMESPACE, cfTargetKey(target));
+}
+
+export async function listRecentTargets(limit = 10): Promise<TCfTarget[]> {
+  const entries = await readAllEntries<TCfTarget>(RECENT_NAMESPACE);
+  return Object.values(entries)
+    .map((entry) => entry.data)
+    .sort((left, right) => String(right.lastUsedAt ?? "").localeCompare(String(left.lastUsedAt ?? "")))
+    .slice(0, limit);
+}
+
+export async function addRecentTarget(target: TCfTarget): Promise<void> {
+  const recent: TCfTarget = { ...target, lastUsedAt: new Date().toISOString() };
+  await writeEntry(RECENT_NAMESPACE, cfTargetKey(recent), toEntry(recent));
+
+  const entries = await readAllEntries<TCfTarget>(RECENT_NAMESPACE);
+  const sorted = Object.values(entries)
+    .map((entry) => entry.data)
+    .sort((left, right) => String(right.lastUsedAt ?? "").localeCompare(String(left.lastUsedAt ?? "")));
+
+  for (const stale of sorted.slice(MAX_RECENT)) {
+    await removeEntry(RECENT_NAMESPACE, cfTargetKey(stale)).catch(() => undefined);
+  }
+}

package/src/core/cf/cf-target.types.ts

@@ -0,0 +1,17 @@
+export type TCfTarget = {
+  region: string;
+  apiEndpoint: string;
+  org: string;
+  space: string;
+  isFavorite?: boolean;
+  lastUsedAt?: string;
+  lastRefreshedAt?: string;
+};
+
+export function cfTargetKey(target: Pick<TCfTarget, "region" | "org" | "space">): string {
+  return `${target.region}::${target.org}::${target.space || ""}`;
+}
+
+export function cfTargetLabel(target: Pick<TCfTarget, "region" | "org" | "space">): string {
+  return `${target.region} / ${target.org}${target.space ? ` / ${target.space}` : ""}`;
+}