deployCache.ts

/*
 * Copyright 2026, Salesforce, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import { Global, TTLConfig } from '@salesforce/core';
import { Duration } from '@salesforce/kit';
import { JsonMap } from '@salesforce/ts-types';
import { DeployOptions, CachedOptions, cacheMessages } from './deploy.js';
import { maybeDestroyManifest } from './manifestCache.js';

export class DeployCache extends TTLConfig<TTLConfig.Options, CachedOptions> {
  public static getFileName(): string {
    return 'deploy-cache.json';
  }

  public static getDefaultOptions(): TTLConfig.Options {
    return {
      isGlobal: true,
      isState: true,
      filename: DeployCache.getFileName(),
      stateFolder: Global.SF_STATE_FOLDER,
      ttl: Duration.days(3),
    };
  }

  /**
   *
   * @param key jobId
   * @param value a DeployOptions object (wait is a duration, can use non-manifest options)
   * @param manifestFilePath the path to the manifest file generated by the deploy
   */
  public static async set(key: string, value: Partial<DeployOptions>): Promise<void> {
    const cache = await DeployCache.create();
    // remove properties we won't cache or that are not primitives
    const { 'metadata-dir': mdDir, 'source-dir': sourceDir, wait, ...cleanValue } = value;
    cache.set(key, { ...cleanValue, wait: wait?.minutes ?? 33, isMdapi: Boolean(mdDir) });
    await cache.write();
  }

  public static async unset(key: string): Promise<void> {
    const cache = await DeployCache.create();
    cache.unset(ensure18(key, cache));
    await Promise.all([cache.write(), maybeDestroyManifest(key)]);
  }

  public static async update(key: string, obj: JsonMap): Promise<void> {
    const cache = await DeployCache.create();
    cache.update(ensure18(key, cache), obj);
    await cache.write();
  }

  public update(key: string, obj: JsonMap): void {
    super.update(ensure18(key, this), obj);
  }

  /** will return an 18 character ID if throwOnNotFound is true (because the cache can be used to shift 15 to 18) */
  public resolveLatest(useMostRecent: boolean, key: string | undefined, throwOnNotFound?: boolean): string {
    const resolvedKey = useMostRecent ? this.getLatestKey() : key;
    if (!resolvedKey) throw cacheMessages.createError('error.NoRecentJobId');

    const match = this.maybeGet(resolvedKey);

    if (throwOnNotFound === true && !match) {
      throw cacheMessages.createError('error.NoMatchingJobId', [resolvedKey]);
    }

    return throwOnNotFound ? ensure18(resolvedKey, this) : resolvedKey;
  }

  /**
   * @deprecated.  Use maybeGet to handle both 15 and 18 char IDs
   * returns 18-char ID unmodified, regardless of whether it's in cache or not
   * returns 15-char ID if it matches a key in the cache, otherwise throws
   */
  public resolveLongId(jobId: string): string {
    return ensure18(jobId, this);
  }

  /**
   *
   * @deprecated.  Use maybeGet because the typings are wrong in sfdx-core
   */
  public get(jobId: string): TTLConfig.Entry<CachedOptions> {
    return super.get(this.resolveLongId(jobId));
  }

  /**
   * works with 18 and 15-character IDs.
   * Prefer 18 as that's how the cache is keyed.
   * Returns undefined if no match is found.
   */
  public maybeGet(jobId: string): TTLConfig.Entry<CachedOptions> | undefined {
    if (jobId.length === 18) {
      return super.get(jobId);
    }
    if (jobId.length === 15) {
      const match = this.keys().find((k) => k.startsWith(jobId));
      return match ? super.get(match) : undefined;
    }
    throw cacheMessages.createError('error.InvalidJobId', [jobId]);
  }
}

/**
 * if the jobId is 15 characters, use the cache to convert to 18
 * will throw if the value is not in the cache
 */
const ensure18 = (jobId: string, cache: DeployCache): string => {
  if (jobId.length === 18) {
    return jobId;
  } else if (jobId.length === 15) {
    const match = cache.keys().find((k) => k.startsWith(jobId));
    if (match) {
      return match;
    }
    throw cacheMessages.createError('error.NoMatchingJobId', [jobId]);
  } else {
    throw cacheMessages.createError('error.InvalidJobId', [jobId]);
  }
};