@xrmforge/typegen 0.3.0 → 0.5.0

package/dist/index.js

@@ -13,6 +13,7 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["META_SOLUTION_NOT_FOUND"] = "META_3002";
   ErrorCode2["META_FORM_PARSE_FAILED"] = "META_3003";
   ErrorCode2["META_ATTRIBUTE_UNKNOWN_TYPE"] = "META_3004";
+  ErrorCode2["META_VERSION_STAMP_EXPIRED"] = "META_3005";
   ErrorCode2["GEN_OUTPUT_WRITE_FAILED"] = "GEN_4001";
   ErrorCode2["GEN_TEMPLATE_FAILED"] = "GEN_4002";
   ErrorCode2["GEN_INVALID_IDENTIFIER"] = "GEN_4003";
@@ -331,6 +332,8 @@ var DataverseHttpClient = class {
   maxRateLimitRetries;
   readOnly;
   cachedToken = null;
+  /** Pending token refresh promise (prevents concurrent token requests) */
+  pendingTokenRefresh = null;
   // Semaphore for concurrency control (non-recursive)
   activeConcurrentRequests = 0;
   waitQueue = [];
@@ -471,18 +474,32 @@ var DataverseHttpClient = class {
     if (this.cachedToken && this.cachedToken.expiresAt - Date.now() > TOKEN_BUFFER_MS) {
       return this.cachedToken.token;
     }
+    if (this.pendingTokenRefresh) {
+      return this.pendingTokenRefresh;
+    }
+    this.pendingTokenRefresh = this.refreshToken();
+    try {
+      return await this.pendingTokenRefresh;
+    } finally {
+      this.pendingTokenRefresh = null;
+    }
+  }
+  /** Internal: actually acquire a new token from the credential provider. */
+  async refreshToken() {
     log2.debug("Requesting new access token");
     const scope = `${this.baseUrl}/.default`;
     let tokenResponse;
     try {
       tokenResponse = await this.credential.getToken(scope);
     } catch (error) {
+      const cause = error instanceof Error ? error.message : String(error);
       throw new AuthenticationError(
         "AUTH_1003" /* AUTH_TOKEN_FAILED */,
-        `Failed to acquire access token for ${this.baseUrl}. Verify your authentication configuration.`,
+        `Failed to acquire access token for ${this.baseUrl}. Verify your authentication configuration.
+Cause: ${cause}`,
         {
           environmentUrl: this.baseUrl,
-          originalError: error instanceof Error ? error.message : String(error)
+          originalError: cause
         }
       );
     }
@@ -508,10 +525,10 @@ var DataverseHttpClient = class {
    * The semaphore is acquired ONCE per logical request. Retries happen
    * INSIDE the semaphore to avoid the recursive slot exhaustion bug.
    */
-  async executeWithConcurrency(url, signal) {
+  async executeWithConcurrency(url, signal, method = "GET", requestBody) {
     await this.acquireSlot();
     try {
-      return await this.executeWithRetry(url, 1, 0, signal);
+      return await this.executeWithRetry(url, 1, 0, signal, method, requestBody);
     } finally {
       this.releaseSlot();
     }
@@ -521,10 +538,10 @@ var DataverseHttpClient = class {
       this.activeConcurrentRequests++;
       return Promise.resolve();
     }
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       this.waitQueue.push(() => {
         this.activeConcurrentRequests++;
-        resolve();
+        resolve2();
       });
     });
   }
@@ -534,7 +551,7 @@ var DataverseHttpClient = class {
     if (next) next();
   }
   // ─── Retry Logic (runs INSIDE a single concurrency slot) ─────────────────
-  async executeWithRetry(url, attempt, rateLimitRetries = 0, signal) {
+  async executeWithRetry(url, attempt, rateLimitRetries = 0, signal, method = "GET", requestBody) {
     if (signal?.aborted) {
       throw new ApiRequestError(
         "API_2001" /* API_REQUEST_FAILED */,
@@ -549,17 +566,21 @@ var DataverseHttpClient = class {
     signal?.addEventListener("abort", onUserAbort, { once: true });
     let response;
     try {
-      log2.debug(`GET ${url}`, { attempt });
+      log2.debug(`${method} ${url}`, { attempt });
+      const headers = {
+        Authorization: `Bearer ${token}`,
+        "OData-MaxVersion": "4.0",
+        "OData-Version": "4.0",
+        Accept: "application/json",
+        Prefer: 'odata.include-annotations="*"'
+      };
+      if (method === "POST") {
+        headers["Content-Type"] = "application/json";
+      }
       response = await fetch(url, {
-        method: "GET",
-        // Explicit: never rely on default
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "OData-MaxVersion": "4.0",
-          "OData-Version": "4.0",
-          Accept: "application/json",
-          Prefer: 'odata.include-annotations="*"'
-        },
+        method,
+        headers,
+        body: requestBody !== void 0 ? JSON.stringify(requestBody) : void 0,
         signal: controller.signal
       });
     } catch (fetchError) {
@@ -579,7 +600,7 @@ var DataverseHttpClient = class {
             url
           });
           await this.sleep(delay);
-          return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal);
+          return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal, method, requestBody);
         }
         throw new ApiRequestError(
           "API_2005" /* API_TIMEOUT */,
@@ -594,7 +615,7 @@ var DataverseHttpClient = class {
           error: fetchError instanceof Error ? fetchError.message : String(fetchError)
         });
         await this.sleep(delay);
-        return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal);
+        return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal, method, requestBody);
       }
       throw new ApiRequestError(
         "API_2001" /* API_REQUEST_FAILED */,
@@ -609,12 +630,12 @@ var DataverseHttpClient = class {
       signal?.removeEventListener("abort", onUserAbort);
     }
     if (!response.ok) {
-      return this.handleHttpError(response, url, attempt, rateLimitRetries, signal);
+      return this.handleHttpError(response, url, attempt, rateLimitRetries, signal, method, requestBody);
     }
-    log2.debug(`GET ${url} -> ${response.status}`, { attempt });
+    log2.debug(`${method} ${url} -> ${response.status}`, { attempt });
     return response.json();
   }
-  async handleHttpError(response, url, attempt, rateLimitRetries, signal) {
+  async handleHttpError(response, url, attempt, rateLimitRetries, signal, method = "GET", requestBody) {
     const body = await response.text();
     if (response.status === 429) {
       if (rateLimitRetries >= this.maxRateLimitRetries) {
@@ -631,12 +652,12 @@ var DataverseHttpClient = class {
         retryAfterHeader
       });
       await this.sleep(retryAfterMs);
-      return this.executeWithRetry(url, attempt, rateLimitRetries + 1, signal);
+      return this.executeWithRetry(url, attempt, rateLimitRetries + 1, signal, method, requestBody);
     }
     if (response.status === 401 && attempt === 1) {
       log2.warn("HTTP 401 received, clearing token cache and retrying");
       this.cachedToken = null;
-      return this.executeWithRetry(url, attempt + 1, 0, signal);
+      return this.executeWithRetry(url, attempt + 1, 0, signal, method, requestBody);
     }
     if (response.status >= 500 && attempt <= this.maxRetries) {
       const delay = this.calculateBackoff(attempt);
@@ -644,7 +665,7 @@ var DataverseHttpClient = class {
         `Server error ${response.status}, retrying in ${delay}ms (${attempt}/${this.maxRetries})`
       );
       await this.sleep(delay);
-      return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal);
+      return this.executeWithRetry(url, attempt + 1, rateLimitRetries, signal, method, requestBody);
     }
     const errorCode = response.status === 401 ? "API_2004" /* API_UNAUTHORIZED */ : response.status === 404 ? "API_2003" /* API_NOT_FOUND */ : "API_2001" /* API_REQUEST_FAILED */;
     throw new ApiRequestError(
@@ -667,7 +688,7 @@ var DataverseHttpClient = class {
     return Math.min(exponential + jitter, MAX_BACKOFF_MS);
   }
   sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return new Promise((resolve2) => setTimeout(resolve2, ms));
   }
 };
 
@@ -1243,10 +1264,12 @@ var MetadataCache = class {
   cacheDir;
   cacheFilePath;
   /**
-   * @param projectRoot - Root directory of the project (where .xrmforge/ will be created)
+   * @param cacheDir - Directory where cache files are stored.
+   *   Can be an absolute path or relative to cwd.
+   *   Defaults to ".xrmforge/cache" when constructed without argument.
    */
-  constructor(projectRoot) {
-    this.cacheDir = path.join(projectRoot, CACHE_DIR);
+  constructor(cacheDir = CACHE_DIR) {
+    this.cacheDir = path.resolve(cacheDir);
     this.cacheFilePath = path.join(this.cacheDir, CACHE_FILE);
   }
   /**
@@ -1362,6 +1385,98 @@ var MetadataCache = class {
   }
 };
 
+// src/metadata/change-detector.ts
+var log6 = createLogger("change-detector");
+var EXPIRED_VERSION_STAMP_ERROR = "0x80044352";
+var ChangeDetector = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Detect which entities have changed since the given version stamp.
+   *
+   * @param clientVersionStamp - The ServerVersionStamp from the last run (from cache)
+   * @returns Changed entity names, deleted entity names, and new version stamp
+   * @throws {MetadataError} with META_VERSION_STAMP_EXPIRED if stamp is too old (>90 days)
+   */
+  async detectChanges(clientVersionStamp) {
+    log6.info("Detecting metadata changes since last run");
+    const query = {
+      Criteria: {
+        FilterOperator: "And",
+        Conditions: []
+      },
+      Properties: {
+        AllProperties: false,
+        PropertyNames: ["LogicalName"]
+      }
+    };
+    const queryJson = encodeURIComponent(JSON.stringify(query));
+    const deletedFilter = `Microsoft.Dynamics.CRM.DeletedMetadataFilters'Default'`;
+    const path2 = `/RetrieveMetadataChanges(Query=@q,ClientVersionStamp=@s,DeletedMetadataFilters=@d)?@q=${queryJson}&@s='${clientVersionStamp}'&@d=${deletedFilter}`;
+    let response;
+    try {
+      response = await this.http.get(path2);
+    } catch (error) {
+      if (this.isExpiredVersionStampError(error)) {
+        throw new MetadataError(
+          "META_3005" /* META_VERSION_STAMP_EXPIRED */,
+          "Cached version stamp has expired (>90 days). A full metadata refresh is required.",
+          { clientVersionStamp }
+        );
+      }
+      throw error;
+    }
+    const changedEntityNames = (response.EntityMetadata ?? []).filter((e) => e.HasChanged !== false).map((e) => e.LogicalName).filter(Boolean);
+    const deletedEntityNames = [];
+    if (response.DeletedMetadata?.Keys) {
+      log6.info(`${response.DeletedMetadata.Keys.length} entity metadata IDs were deleted`);
+    }
+    const newVersionStamp = response.ServerVersionStamp;
+    log6.info(`Change detection complete: ${changedEntityNames.length} changed, ${deletedEntityNames.length} deleted`, {
+      changedEntityNames: changedEntityNames.length <= 10 ? changedEntityNames : `${changedEntityNames.length} entities`,
+      newVersionStamp: newVersionStamp.substring(0, 20) + "..."
+    });
+    return {
+      changedEntityNames,
+      deletedEntityNames,
+      newVersionStamp
+    };
+  }
+  /**
+   * Perform an initial metadata query to get the first ServerVersionStamp.
+   * This is used on the very first run (no cache exists).
+   *
+   * @returns The initial server version stamp
+   */
+  async getInitialVersionStamp() {
+    log6.info("Fetching initial server version stamp");
+    const query = {
+      Criteria: {
+        FilterOperator: "And",
+        Conditions: []
+      },
+      Properties: {
+        AllProperties: false,
+        PropertyNames: ["LogicalName"]
+      }
+    };
+    const queryParam = encodeURIComponent(JSON.stringify(query));
+    const path2 = `/RetrieveMetadataChanges(Query=@q)?@q=${queryParam}`;
+    const response = await this.http.get(path2);
+    log6.info("Initial version stamp acquired");
+    return response.ServerVersionStamp;
+  }
+  /** Check if an error is the expired version stamp error (0x80044352) */
+  isExpiredVersionStampError(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    const errorRecord = error;
+    const contextBody = errorRecord?.context ? String(errorRecord.context["responseBody"] ?? "") : "";
+    const combined = msg + contextBody;
+    return combined.includes(EXPIRED_VERSION_STAMP_ERROR) || combined.includes("ExpiredVersionStamp");
+  }
+};
+
 // src/metadata/labels.ts
 var DEFAULT_LABEL_CONFIG = {
   primaryLanguage: 1033
@@ -1455,10 +1570,12 @@ function getLabelLanguagesParam(config) {
 }
 
 // src/generators/type-mapping.ts
+var log7 = createLogger("type-mapping");
 function getEntityPropertyType(attributeType, isLookup = false) {
   if (isLookup) return "string";
   const mapping = ENTITY_TYPE_MAP[attributeType];
   if (mapping) return mapping;
+  log7.warn(`Unmapped AttributeType "${attributeType}" falling back to "unknown"`);
   return "unknown";
 }
 var ENTITY_TYPE_MAP = {
@@ -1497,6 +1614,7 @@ var ENTITY_TYPE_MAP = {
 function getFormAttributeType(attributeType) {
   const mapping = FORM_ATTRIBUTE_TYPE_MAP[attributeType];
   if (mapping) return mapping;
+  log7.warn(`Unmapped form AttributeType "${attributeType}" falling back to generic Attribute`);
   return "Xrm.Attributes.Attribute";
 }
 var FORM_ATTRIBUTE_TYPE_MAP = {
@@ -1990,6 +2108,50 @@ function generateFormInterface(form, entityLogicalName, attributeMap, options =
       lines.push("");
     }
   }
+  const specialControls = form.allSpecialControls || [];
+  const subgrids = specialControls.filter((sc) => sc.controlType === "subgrid" || sc.controlType === "editablegrid");
+  const quickViews = specialControls.filter((sc) => sc.controlType === "quickview");
+  if (subgrids.length > 0) {
+    const subgridsEnumName = `${baseName}FormSubgrids`;
+    lines.push(`  /** Subgrid constants for "${form.name}" (compile-time only, zero runtime) */`);
+    lines.push(`  const enum ${subgridsEnumName} {`);
+    const usedMembers = /* @__PURE__ */ new Set();
+    for (const sg of subgrids) {
+      let member = toSafeFormName(sg.id) || toPascalCase(sg.id);
+      const original = member;
+      let counter = 2;
+      while (usedMembers.has(member)) {
+        member = `${original}${counter}`;
+        counter++;
+      }
+      usedMembers.add(member);
+      const label = sg.targetEntityType ? `Subgrid: ${sg.targetEntityType}` : `Subgrid`;
+      lines.push(`    /** ${label} */`);
+      lines.push(`    ${member} = '${sg.id}',`);
+    }
+    lines.push("  }");
+    lines.push("");
+  }
+  if (quickViews.length > 0) {
+    const qvEnumName = `${baseName}FormQuickViews`;
+    lines.push(`  /** Quick View constants for "${form.name}" (compile-time only, zero runtime) */`);
+    lines.push(`  const enum ${qvEnumName} {`);
+    const usedMembers = /* @__PURE__ */ new Set();
+    for (const qv of quickViews) {
+      let member = toSafeFormName(qv.id) || toPascalCase(qv.id);
+      const original = member;
+      let counter = 2;
+      while (usedMembers.has(member)) {
+        member = `${original}${counter}`;
+        counter++;
+      }
+      usedMembers.add(member);
+      lines.push(`    /** Quick View */`);
+      lines.push(`    ${member} = '${qv.id}',`);
+    }
+    lines.push("  }");
+    lines.push("");
+  }
   lines.push(`  /** ${form.name} */`);
   lines.push(`  interface ${interfaceName} extends Omit<Xrm.FormContext, 'getAttribute' | 'getControl'> {`);
   lines.push(`    /** Typisierter Feldzugriff: nur Felder die auf diesem Formular existieren */`);
@@ -1999,7 +2161,6 @@ function generateFormInterface(form, entityLogicalName, attributeMap, options =
   lines.push("");
   lines.push(`    /** Typisierter Control-Zugriff: nur Controls die auf diesem Formular existieren */`);
   lines.push(`    getControl<K extends ${fieldsTypeName}>(name: K): ${ctrlMapName}[K];`);
-  const specialControls = form.allSpecialControls || [];
   for (const sc of specialControls) {
     const xrmType = specialControlToXrmType(sc.controlType);
     if (xrmType) {
@@ -2380,6 +2541,7 @@ function createBoundAction(operationName, entityLogicalName, paramMeta) {
 }
 function createUnboundAction(operationName, paramMeta) {
   return {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- return type varies (Response or parsed JSON)
     async execute(params) {
       const req = buildUnboundRequest(
         operationName,
@@ -2664,7 +2826,7 @@ function groupCustomApis(apis) {
 }
 
 // src/orchestrator/file-writer.ts
-import { mkdir, writeFile, readFile } from "fs/promises";
+import { mkdir, writeFile, readFile, unlink } from "fs/promises";
 import { join as join2, dirname } from "path";
 async function writeGeneratedFile(outputDir, file) {
   const absolutePath = join2(outputDir, file.relativePath);
@@ -2696,6 +2858,24 @@ async function writeAllFiles(outputDir, files) {
   }
   return result;
 }
+async function deleteOrphanedFiles(outputDir, deletedEntityNames) {
+  let deleted = 0;
+  const subdirs = ["entities", "optionsets", "forms"];
+  for (const entityName of deletedEntityNames) {
+    for (const subdir of subdirs) {
+      const filePath = join2(outputDir, subdir, `${entityName}.d.ts`);
+      try {
+        await unlink(filePath);
+        deleted++;
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+    }
+  }
+  return deleted;
+}
 var GENERATED_HEADER = `// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 // This file was generated by @xrmforge/typegen. Do not edit manually.
 // Re-run 'xrmforge generate' to update.
@@ -2742,11 +2922,6 @@ var TypeGenerationOrchestrator = class {
   constructor(credential, config, logger) {
     this.credential = credential;
     this.logger = logger ?? createLogger("orchestrator");
-    if (config.useCache) {
-      throw new Error(
-        "Metadata caching is not yet implemented (planned for v0.2.0). Remove the useCache option or set it to false."
-      );
-    }
     this.config = {
       environmentUrl: config.environmentUrl,
       entities: [...config.entities],
@@ -2781,7 +2956,8 @@ var TypeGenerationOrchestrator = class {
     }
     this.logger.info("Starting type generation", {
       entities: this.config.entities,
-      outputDir: this.config.outputDir
+      outputDir: this.config.outputDir,
+      useCache: this.config.useCache
     });
     const httpClient = new DataverseHttpClient({
       environmentUrl: this.config.environmentUrl,
@@ -2804,80 +2980,71 @@ var TypeGenerationOrchestrator = class {
         durationMs: Date.now() - startTime
       };
     }
-    this.logger.info(`Processing ${this.config.entities.length} entities in parallel`);
-    const settled = await Promise.allSettled(
-      this.config.entities.map((entityName) => {
-        if (signal?.aborted) {
-          return Promise.reject(new Error("Generation aborted"));
+    let cacheStats;
+    const entitiesToFetch = new Set(this.config.entities);
+    const cachedEntityInfos = {};
+    let cache;
+    let newVersionStamp = null;
+    const deletedEntityNames = [];
+    if (this.config.useCache) {
+      const cacheResult = await this.resolveCache(httpClient, entitiesToFetch);
+      cache = cacheResult.cache;
+      newVersionStamp = cacheResult.newVersionStamp;
+      cacheStats = cacheResult.stats;
+      for (const [name, info] of Object.entries(cacheResult.cachedEntities)) {
+        cachedEntityInfos[name] = info;
+        entitiesToFetch.delete(name);
+      }
+      deletedEntityNames.push(...cacheResult.deletedEntityNames);
+    }
+    const fetchList = [...entitiesToFetch];
+    const failedEntities = /* @__PURE__ */ new Map();
+    if (fetchList.length > 0) {
+      this.logger.info(`Fetching ${fetchList.length} entities from Dataverse`);
+      const settled = await Promise.allSettled(
+        fetchList.map((entityName) => {
+          if (signal?.aborted) {
+            return Promise.reject(new Error("Generation aborted"));
+          }
+          return metadataClient.getEntityTypeInfo(entityName).then((info) => {
+            this.logger.info(`Fetched entity: ${entityName}`);
+            return { entityName, info };
+          });
+        })
+      );
+      for (let i = 0; i < settled.length; i++) {
+        const outcome = settled[i];
+        const entityName = fetchList[i];
+        if (outcome.status === "fulfilled") {
+          cachedEntityInfos[outcome.value.entityName] = outcome.value.info;
+        } else {
+          const errorMsg = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+          this.logger.error(`Failed to fetch entity: ${entityName}`, { error: outcome.reason });
+          failedEntities.set(entityName, errorMsg);
         }
-        return this.processEntity(entityName, metadataClient).then((result) => {
-          this.logger.info(`Completed entity: ${entityName} (${result.files.length} files)`);
-          return result;
-        });
-      })
-    );
-    for (let i = 0; i < settled.length; i++) {
-      const outcome = settled[i];
-      const entityName = this.config.entities[i];
-      if (outcome.status === "fulfilled") {
-        entityResults.push(outcome.value);
-        allFiles.push(...outcome.value.files);
-      } else {
-        const errorMsg = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
-        this.logger.error(`Failed to process entity: ${entityName}`, { error: outcome.reason });
+      }
+    }
+    this.logger.info(`Generating types for ${this.config.entities.length - failedEntities.size} entities`);
+    for (const entityName of this.config.entities) {
+      if (signal?.aborted) break;
+      if (failedEntities.has(entityName)) {
         entityResults.push({
           entityLogicalName: entityName,
           files: [],
-          warnings: [`Failed to process: ${errorMsg}`]
+          warnings: [`Failed to process: ${failedEntities.get(entityName)}`]
         });
+        continue;
       }
+      const entityInfo = cachedEntityInfos[entityName];
+      if (!entityInfo) continue;
+      const result = this.generateEntityFiles(entityName, entityInfo);
+      this.logger.info(`Generated entity: ${entityName} (${result.files.length} files)`);
+      entityResults.push(result);
+      allFiles.push(...result.files);
     }
     if (this.config.generateActions && !signal?.aborted) {
-      this.logger.info("Fetching Custom APIs...");
-      let customApis = await metadataClient.getCustomApis();
-      if (this.config.actionsFilter) {
-        const prefix = this.config.actionsFilter.toLowerCase();
-        const before = customApis.length;
-        customApis = customApis.filter((api) => api.api.uniquename.toLowerCase().startsWith(prefix));
-        this.logger.info(`Filtered Custom APIs by prefix "${this.config.actionsFilter}": ${before} -> ${customApis.length}`);
-      }
-      if (customApis.length > 0) {
-        const importPath = "@xrmforge/typegen";
-        const grouped = groupCustomApis(customApis);
-        for (const [key, apis] of grouped.actions) {
-          const entityName = key === "global" ? void 0 : key;
-          const declarations = generateActionDeclarations(apis, false, entityName, { importPath });
-          const module = generateActionModule(apis, false, { importPath });
-          allFiles.push({
-            relativePath: `actions/${key}.d.ts`,
-            content: addGeneratedHeader(declarations),
-            type: "action"
-          });
-          allFiles.push({
-            relativePath: `actions/${key}.ts`,
-            content: addGeneratedHeader(module),
-            type: "action"
-          });
-        }
-        for (const [key, apis] of grouped.functions) {
-          const entityName = key === "global" ? void 0 : key;
-          const declarations = generateActionDeclarations(apis, true, entityName, { importPath });
-          const module = generateActionModule(apis, true, { importPath });
-          allFiles.push({
-            relativePath: `functions/${key}.d.ts`,
-            content: addGeneratedHeader(declarations),
-            type: "action"
-          });
-          allFiles.push({
-            relativePath: `functions/${key}.ts`,
-            content: addGeneratedHeader(module),
-            type: "action"
-          });
-        }
-        this.logger.info(`Generated ${grouped.actions.size} action groups, ${grouped.functions.size} function groups`);
-      } else {
-        this.logger.info("No Custom APIs found");
-      }
+      const actionFiles = await this.generateActions(metadataClient);
+      allFiles.push(...actionFiles);
     }
     if (this.config.entities.length > 0) {
       const entityNamesContent = generateEntityNamesEnum(this.config.entities, {
@@ -2899,6 +3066,15 @@ var TypeGenerationOrchestrator = class {
       allFiles.push(indexFile);
     }
     const writeResult = await writeAllFiles(this.config.outputDir, allFiles);
+    if (deletedEntityNames.length > 0) {
+      const deleted = await deleteOrphanedFiles(this.config.outputDir, deletedEntityNames);
+      if (deleted > 0) {
+        this.logger.info(`Deleted ${deleted} orphaned files for removed entities`);
+      }
+    }
+    if (this.config.useCache && cache) {
+      await this.updateCache(cache, cachedEntityInfos, deletedEntityNames, newVersionStamp);
+    }
     const durationMs = Date.now() - startTime;
     const entityWarnings = entityResults.reduce((sum, r) => sum + r.warnings.length, 0);
     const totalWarnings = entityWarnings + writeResult.warnings.length;
@@ -2911,22 +3087,129 @@ var TypeGenerationOrchestrator = class {
       filesUnchanged: writeResult.unchanged,
       totalFiles: allFiles.length,
       totalWarnings,
-      durationMs
+      durationMs,
+      cacheUsed: cacheStats?.cacheUsed ?? false
     });
     return {
       entities: entityResults,
       totalFiles: allFiles.length,
       totalWarnings,
-      durationMs
+      durationMs,
+      cacheStats
+    };
+  }
+  /**
+   * Resolve the cache: load existing cache, detect changes, determine which
+   * entities need to be fetched vs. can be served from cache.
+   *
+   * On any failure (corrupt cache, expired stamp), falls back to full refresh.
+   */
+  async resolveCache(httpClient, requestedEntities) {
+    const cache = new MetadataCache(this.config.cacheDir);
+    const changeDetector = new ChangeDetector(httpClient);
+    let cacheData;
+    try {
+      cacheData = await cache.load(this.config.environmentUrl);
+    } catch {
+      this.logger.warn("Failed to load metadata cache, performing full refresh");
+      cacheData = null;
+    }
+    if (!cacheData || !cacheData.manifest.serverVersionStamp) {
+      this.logger.info("No valid cache found, performing full metadata refresh");
+      const stamp = await changeDetector.getInitialVersionStamp();
+      return {
+        cache,
+        cachedEntities: {},
+        deletedEntityNames: [],
+        newVersionStamp: stamp,
+        stats: {
+          cacheUsed: true,
+          fullRefresh: true,
+          entitiesFromCache: 0,
+          entitiesFetched: requestedEntities.size,
+          entitiesDeleted: 0
+        }
+      };
+    }
+    let changeResult;
+    try {
+      changeResult = await changeDetector.detectChanges(cacheData.manifest.serverVersionStamp);
+    } catch (error) {
+      const isExpired = error instanceof Error && error.message.includes("META_3005" /* META_VERSION_STAMP_EXPIRED */);
+      if (isExpired) {
+        this.logger.warn("Cache version stamp expired (>90 days), performing full refresh");
+      } else {
+        this.logger.warn("Change detection failed, performing full refresh", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+      const stamp = await changeDetector.getInitialVersionStamp();
+      return {
+        cache,
+        cachedEntities: {},
+        deletedEntityNames: [],
+        newVersionStamp: stamp,
+        stats: {
+          cacheUsed: true,
+          fullRefresh: true,
+          entitiesFromCache: 0,
+          entitiesFetched: requestedEntities.size,
+          entitiesDeleted: 0
+        }
+      };
+    }
+    const changedSet = new Set(changeResult.changedEntityNames);
+    const cachedEntities = {};
+    let entitiesFromCache = 0;
+    let entitiesFetched = 0;
+    for (const entityName of requestedEntities) {
+      if (changedSet.has(entityName) || !cacheData.entityTypeInfos[entityName]) {
+        entitiesFetched++;
+      } else {
+        cachedEntities[entityName] = cacheData.entityTypeInfos[entityName];
+        entitiesFromCache++;
+      }
+    }
+    const deletedEntityNames = changeResult.deletedEntityNames.filter(
+      (name) => requestedEntities.has(name)
+    );
+    this.logger.info(`Cache delta: ${entitiesFromCache} from cache, ${entitiesFetched} to fetch, ${deletedEntityNames.length} deleted`);
+    return {
+      cache,
+      cachedEntities,
+      deletedEntityNames,
+      newVersionStamp: changeResult.newVersionStamp,
+      stats: {
+        cacheUsed: true,
+        fullRefresh: false,
+        entitiesFromCache,
+        entitiesFetched,
+        entitiesDeleted: deletedEntityNames.length
+      }
     };
   }
   /**
-   * Process a single entity: fetch metadata, generate all output files.
+   * Update the metadata cache after a successful generation run.
    */
-  async processEntity(entityName, metadataClient) {
+  async updateCache(cache, entityTypeInfos, deletedEntityNames, newVersionStamp) {
+    try {
+      if (deletedEntityNames.length > 0) {
+        await cache.removeEntities(this.config.environmentUrl, deletedEntityNames, newVersionStamp);
+      }
+      await cache.save(this.config.environmentUrl, entityTypeInfos, newVersionStamp);
+      this.logger.info("Metadata cache updated");
+    } catch (error) {
+      this.logger.warn("Failed to update metadata cache", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  /**
+   * Generate all output files for a single entity from its metadata.
+   */
+  generateEntityFiles(entityName, entityInfo) {
     const warnings = [];
     const files = [];
-    const entityInfo = await metadataClient.getEntityTypeInfo(entityName);
     if (this.config.generateEntities) {
       const entityContent = generateEntityInterface(entityInfo, {
         labelConfig: this.config.labelConfig,
@@ -2982,6 +3265,58 @@ var TypeGenerationOrchestrator = class {
     }
     return { entityLogicalName: entityName, files, warnings };
   }
+  /**
+   * Generate Custom API Action/Function executor files.
+   */
+  async generateActions(metadataClient) {
+    const files = [];
+    this.logger.info("Fetching Custom APIs...");
+    let customApis = await metadataClient.getCustomApis();
+    if (this.config.actionsFilter) {
+      const prefix = this.config.actionsFilter.toLowerCase();
+      const before = customApis.length;
+      customApis = customApis.filter((api) => api.api.uniquename.toLowerCase().startsWith(prefix));
+      this.logger.info(`Filtered Custom APIs by prefix "${this.config.actionsFilter}": ${before} -> ${customApis.length}`);
+    }
+    if (customApis.length > 0) {
+      const importPath = "@xrmforge/typegen";
+      const grouped = groupCustomApis(customApis);
+      for (const [key, apis] of grouped.actions) {
+        const entityName = key === "global" ? void 0 : key;
+        const declarations = generateActionDeclarations(apis, false, entityName, { importPath });
+        const module = generateActionModule(apis, false, { importPath });
+        files.push({
+          relativePath: `actions/${key}.d.ts`,
+          content: addGeneratedHeader(declarations),
+          type: "action"
+        });
+        files.push({
+          relativePath: `actions/${key}.ts`,
+          content: addGeneratedHeader(module),
+          type: "action"
+        });
+      }
+      for (const [key, apis] of grouped.functions) {
+        const entityName = key === "global" ? void 0 : key;
+        const declarations = generateActionDeclarations(apis, true, entityName, { importPath });
+        const module = generateActionModule(apis, true, { importPath });
+        files.push({
+          relativePath: `functions/${key}.d.ts`,
+          content: addGeneratedHeader(declarations),
+          type: "action"
+        });
+        files.push({
+          relativePath: `functions/${key}.ts`,
+          content: addGeneratedHeader(module),
+          type: "action"
+        });
+      }
+      this.logger.info(`Generated ${grouped.actions.size} action groups, ${grouped.functions.size} function groups`);
+    } else {
+      this.logger.info("No Custom APIs found");
+    }
+    return files;
+  }
   /**
    * Extract picklist attributes with their OptionSet metadata.
    * Maps the raw EntityTypeInfo data to the format expected by the OptionSet generator.
@@ -3016,6 +3351,7 @@ export {
   ApiRequestError,
   AuthenticationError,
   BindingType,
+  ChangeDetector,
   ClientState,
   ClientType,
   ConfigError,