@salesforce/b2c-tooling-sdk 1.3.2 → 1.5.0

package/dist/cjs/operations/cap/package.d.ts

@@ -0,0 +1,39 @@
+import { type CommerceAppManifest } from './validate.js';
+/**
+ * Options for CAP packaging.
+ */
+export interface CommerceAppPackageOptions {
+    /**
+     * Output path for the zip file.
+     * - If a directory: zip is written to `{outputPath}/{id}-v{version}.zip`
+     * - If a .zip path: written to that exact location
+     * - Default: current working directory
+     */
+    outputPath?: string;
+}
+/**
+ * Result of CAP packaging.
+ */
+export interface CommerceAppPackageResult {
+    /** Absolute path to the produced zip file. */
+    outputPath: string;
+    /** Parsed manifest. */
+    manifest: CommerceAppManifest;
+}
+/**
+ * Packages a CAP directory into a distributable .zip file.
+ *
+ * The zip root directory is named `{id}-v{version}/` as required by the CAP spec.
+ * Reads commerce-app.json to determine the app name and version.
+ *
+ * @param sourceDir - Path to the CAP directory
+ * @param options - Packaging options
+ * @returns Result with the output zip path and manifest
+ *
+ * @example
+ * ```typescript
+ * const result = await commerceAppPackage('./commerce-avalara-tax-app-v0.2.5');
+ * console.log(`Packaged to: ${result.outputPath}`);
+ * ```
+ */
+export declare function commerceAppPackage(sourceDir: string, options?: CommerceAppPackageOptions): Promise<CommerceAppPackageResult>;

package/dist/cjs/operations/cap/package.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Commerce App Package (CAP) packaging.
+ *
+ * Zips a CAP directory into a distributable .zip file with the correct
+ * root directory naming convention ({id}-v{version}/).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import JSZip from 'jszip';
+import { getLogger } from '../../logging/logger.js';
+import { addDirectoryToZip } from '../util/zip.js';
+import { readManifest } from './install.js';
+/**
+ * Packages a CAP directory into a distributable .zip file.
+ *
+ * The zip root directory is named `{id}-v{version}/` as required by the CAP spec.
+ * Reads commerce-app.json to determine the app name and version.
+ *
+ * @param sourceDir - Path to the CAP directory
+ * @param options - Packaging options
+ * @returns Result with the output zip path and manifest
+ *
+ * @example
+ * ```typescript
+ * const result = await commerceAppPackage('./commerce-avalara-tax-app-v0.2.5');
+ * console.log(`Packaged to: ${result.outputPath}`);
+ * ```
+ */
+export async function commerceAppPackage(sourceDir, options = {}) {
+    const logger = getLogger();
+    if (!fs.existsSync(sourceDir)) {
+        throw new Error(`Source directory not found: ${sourceDir}`);
+    }
+    if (!fs.statSync(sourceDir).isDirectory()) {
+        throw new Error(`Source must be a directory: ${sourceDir}`);
+    }
+    const manifest = readManifest(sourceDir);
+    if (!manifest.id || !manifest.version) {
+        throw new Error('commerce-app.json must have "id" and "version" fields');
+    }
+    const archiveDirName = `${manifest.id}-v${manifest.version}`;
+    const zipFilename = `${archiveDirName}.zip`;
+    // Determine output path
+    let outputZipPath;
+    if (!options.outputPath) {
+        outputZipPath = path.resolve(process.cwd(), zipFilename);
+    }
+    else {
+        const resolved = path.resolve(options.outputPath);
+        if (resolved.endsWith('.zip')) {
+            outputZipPath = resolved;
+        }
+        else {
+            outputZipPath = path.join(resolved, zipFilename);
+        }
+    }
+    // Ensure output directory exists
+    await fs.promises.mkdir(path.dirname(outputZipPath), { recursive: true });
+    logger.debug({ sourceDir, outputPath: outputZipPath }, `Packaging CAP: ${archiveDirName}`);
+    const zip = new JSZip();
+    const rootFolder = zip.folder(archiveDirName);
+    await addDirectoryToZip(rootFolder, sourceDir);
+    const buffer = await zip.generateAsync({
+        type: 'nodebuffer',
+        compression: 'DEFLATE',
+        compressionOptions: { level: 9 },
+    });
+    await fs.promises.writeFile(outputZipPath, buffer);
+    logger.debug({ outputPath: outputZipPath }, `CAP packaged to: ${outputZipPath}`);
+    return { outputPath: outputZipPath, manifest };
+}
+//# sourceMappingURL=package.js.map

package/dist/cjs/operations/cap/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../../../../src/operations/cap/package.ts"],"names":[],"mappings":"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"}

package/dist/cjs/operations/cap/pull.d.ts

@@ -0,0 +1,21 @@
+import { B2CInstance } from '../../instance/index.js';
+import type { CommerceFeatureState } from './list.js';
+export interface PullCommerceAppsOptions {
+    outputDir?: string;
+}
+export type PullSource = 'instance' | 'github';
+export interface PulledApp {
+    featureName: string;
+    version: string;
+    domain: string;
+    source: PullSource;
+    extractedPath: string;
+}
+export interface PullCommerceAppsResult {
+    pulled: PulledApp[];
+    failed: Array<{
+        featureName: string;
+        error: string;
+    }>;
+}
+export declare function pullCommerceApps(instance: B2CInstance, features: CommerceFeatureState[], options?: PullCommerceAppsOptions): Promise<PullCommerceAppsResult>;

package/dist/cjs/operations/cap/pull.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import JSZip from 'jszip';
+import { getLogger } from '../../logging/logger.js';
+const GITHUB_RAW_BASE = 'https://raw.githubusercontent.com/SalesforceCommerceCloud/commerce-apps/main';
+export async function pullCommerceApps(instance, features, options = {}) {
+    const logger = getLogger();
+    const outputDir = path.resolve(options.outputDir ?? 'commerce-apps');
+    await fs.promises.mkdir(outputDir, { recursive: true });
+    const pulled = [];
+    const failed = [];
+    for (const feature of features) {
+        const { featureName, featureVersionId, featureDomain } = feature;
+        if (!featureVersionId) {
+            failed.push({ featureName, error: 'No version available' });
+            continue;
+        }
+        const zipFilename = `${featureName}-v${featureVersionId}.zip`;
+        const webdavPath = `Impex/commerce-apps/${zipFilename}`;
+        let zipData = null;
+        let source = 'instance';
+        // Try instance first
+        if (await instance.webdav.exists(webdavPath)) {
+            logger.debug({ path: webdavPath }, `Downloading ${zipFilename} from instance`);
+            zipData = Buffer.from(await instance.webdav.get(webdavPath));
+        }
+        // Fall back to GitHub
+        if (!zipData) {
+            const githubUrl = `${GITHUB_RAW_BASE}/${featureDomain}/${featureName}/${zipFilename}`;
+            logger.warn({ url: githubUrl }, `${zipFilename} not found on instance, trying GitHub`);
+            source = 'github';
+            try {
+                const response = await fetch(githubUrl);
+                if (!response.ok) {
+                    failed.push({ featureName, error: `Not found on instance or GitHub (${githubUrl})` });
+                    continue;
+                }
+                zipData = Buffer.from(await response.arrayBuffer());
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                failed.push({ featureName, error: `GitHub download failed: ${msg}` });
+                continue;
+            }
+        }
+        // Extract zip
+        const zip = await JSZip.loadAsync(zipData);
+        const extractDir = path.join(outputDir, featureName);
+        await fs.promises.mkdir(extractDir, { recursive: true });
+        for (const [filePath, entry] of Object.entries(zip.files)) {
+            if (entry.dir)
+                continue;
+            // Strip the top-level archive directory (e.g. "avalara-tax-v1.1.0/...")
+            const parts = filePath.split('/');
+            const relativePath = parts.length > 1 ? parts.slice(1).join('/') : filePath;
+            const fullPath = path.join(extractDir, relativePath);
+            await fs.promises.mkdir(path.dirname(fullPath), { recursive: true });
+            const content = await entry.async('nodebuffer');
+            await fs.promises.writeFile(fullPath, content);
+        }
+        logger.debug({ featureName, extractDir }, `Extracted ${featureName} to ${extractDir}`);
+        pulled.push({
+            featureName,
+            version: featureVersionId,
+            domain: featureDomain,
+            source,
+            extractedPath: extractDir,
+        });
+    }
+    return { pulled, failed };
+}
+//# sourceMappingURL=pull.js.map

package/dist/cjs/operations/cap/pull.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull.js","sourceRoot":"","sources":["../../../../src/operations/cap/pull.ts"],"names":[],"mappings":"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"}

package/dist/cjs/operations/cap/uninstall.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Commerce App Package (CAP) uninstallation.
+ *
+ * Runs the sfcc-uninstall-commerce-app system job to remove an installed CAP.
+ */
+import { B2CInstance } from '../../instance/index.js';
+import { type JobExecution, type WaitForJobOptions } from '../jobs/run.js';
+/**
+ * Options for CAP uninstallation.
+ */
+export interface CommerceAppUninstallOptions {
+    /** Target site ID to uninstall the app from. */
+    siteId: string;
+    /** Wait options for job completion. */
+    waitOptions?: WaitForJobOptions;
+}
+/**
+ * Result of a CAP uninstallation.
+ */
+export interface CommerceAppUninstallResult {
+    /** Job execution details. */
+    execution: JobExecution;
+    /** App name that was uninstalled. */
+    appName: string;
+}
+/**
+ * Uninstalls a Commerce App from a B2C Commerce instance.
+ *
+ * Executes the sfcc-uninstall-commerce-app system job which removes cartridges,
+ * IMPEX data, and configuration associated with the app from the target site.
+ *
+ * @param instance - B2C instance to uninstall from
+ * @param appName - App ID (from commerce-app.json "id" field, e.g. "avalara-tax")
+ * @param appDomain - App domain (e.g. "tax", "shipping")
+ * @param options - Uninstall options including required siteId
+ * @returns Uninstall result with job execution details
+ * @throws JobExecutionError if the uninstall job fails
+ *
+ * @example
+ * ```typescript
+ * const result = await commerceAppUninstall(instance, 'avalara-tax', 'tax', {
+ *   siteId: 'RefArch',
+ * });
+ * ```
+ */
+export declare function commerceAppUninstall(instance: B2CInstance, appName: string, appDomain: string, options: CommerceAppUninstallOptions): Promise<CommerceAppUninstallResult>;

package/dist/cjs/operations/cap/uninstall.js

@@ -0,0 +1,87 @@
+import { getLogger } from '../../logging/logger.js';
+import { waitForJob, JobExecutionError, getJobLog } from '../jobs/run.js';
+import { normalizeSiteId } from './install.js';
+const UNINSTALL_JOB_ID = 'sfcc-uninstall-commerce-app';
+/**
+ * Uninstalls a Commerce App from a B2C Commerce instance.
+ *
+ * Executes the sfcc-uninstall-commerce-app system job which removes cartridges,
+ * IMPEX data, and configuration associated with the app from the target site.
+ *
+ * @param instance - B2C instance to uninstall from
+ * @param appName - App ID (from commerce-app.json "id" field, e.g. "avalara-tax")
+ * @param appDomain - App domain (e.g. "tax", "shipping")
+ * @param options - Uninstall options including required siteId
+ * @returns Uninstall result with job execution details
+ * @throws JobExecutionError if the uninstall job fails
+ *
+ * @example
+ * ```typescript
+ * const result = await commerceAppUninstall(instance, 'avalara-tax', 'tax', {
+ *   siteId: 'RefArch',
+ * });
+ * ```
+ */
+export async function commerceAppUninstall(instance, appName, appDomain, options) {
+    const logger = getLogger();
+    const { siteId: rawSiteId, waitOptions } = options;
+    const siteId = normalizeSiteId(rawSiteId);
+    logger.debug({ jobId: UNINSTALL_JOB_ID, appName, siteId }, `Executing ${UNINSTALL_JOB_ID} job`);
+    let execution;
+    // Try direct body format first (standard OCAPI format)
+    const { data, error } = await instance.ocapi.POST('/jobs/{job_id}/executions', {
+        params: { path: { job_id: UNINSTALL_JOB_ID } },
+        body: {
+            app_name: appName,
+            app_domain: appDomain,
+            site_id: siteId,
+        },
+    });
+    if (error?.fault?.type === 'UnknownPropertyException' &&
+        error.fault.arguments?.document === 'job_execution_request') {
+        // Retry with parameters format (internal/support users)
+        logger.warn('Retrying with parameters format for internal users');
+        const { data: retryData, error: retryError } = await instance.ocapi.POST('/jobs/{job_id}/executions', {
+            params: { path: { job_id: UNINSTALL_JOB_ID } },
+            body: {
+                parameters: [
+                    { name: 'AppName', value: appName },
+                    { name: 'AppDomain', value: appDomain },
+                    { name: 'SiteId', value: siteId },
+                ],
+            },
+        });
+        if (retryError || !retryData) {
+            throw new Error(retryError?.fault?.message ?? 'Failed to start uninstall job');
+        }
+        execution = retryData;
+    }
+    else if (error || !data) {
+        throw new Error(error?.fault?.message ?? 'Failed to start uninstall job');
+    }
+    else {
+        execution = data;
+    }
+    logger.debug({ jobId: UNINSTALL_JOB_ID, executionId: execution.id }, `Uninstall job started: ${execution.id}`);
+    let finalExecution;
+    try {
+        finalExecution = await waitForJob(instance, UNINSTALL_JOB_ID, execution.id, waitOptions);
+    }
+    catch (err) {
+        if (err instanceof JobExecutionError) {
+            try {
+                const log = await getJobLog(instance, err.execution);
+                logger.error({ jobId: UNINSTALL_JOB_ID, log }, `Job log:\n${log}`);
+            }
+            catch {
+                logger.error({ jobId: UNINSTALL_JOB_ID }, 'Could not retrieve job log');
+            }
+        }
+        throw err;
+    }
+    return {
+        execution: finalExecution,
+        appName,
+    };
+}
+//# sourceMappingURL=uninstall.js.map

package/dist/cjs/operations/cap/uninstall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uninstall.js","sourceRoot":"","sources":["../../../../src/operations/cap/uninstall.ts"],"names":[],"mappings":"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"}

package/dist/cjs/operations/cap/validate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Manifest from commerce-app.json.
+ */
+export interface CommerceAppManifest {
+    id: string;
+    name: string;
+    version: string;
+    domain: string;
+    description?: string;
+    publisher?: {
+        name: string;
+        url?: string;
+        support?: string;
+    };
+    dependencies?: Record<string, string>;
+}
+/**
+ * Result of CAP validation.
+ */
+export interface CapValidationResult {
+    /** Whether the CAP is valid (no errors). */
+    valid: boolean;
+    /** Blocking errors — a CAP with errors cannot be installed. */
+    errors: string[];
+    /** Advisory warnings — a CAP with warnings can still be installed. */
+    warnings: string[];
+    /** Parsed manifest from commerce-app.json (if parseable). */
+    manifest?: CommerceAppManifest;
+}
+/**
+ * Validates a Commerce App Package (CAP) directory or zip file.
+ *
+ * Checks required files, manifest schema, and cartridge structure rules.
+ * This is a purely local operation — no B2C instance required.
+ *
+ * @param target - Path to a CAP directory or .zip file
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = await validateCap('./my-commerce-app-v1.0.0');
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateCap(target: string): Promise<CapValidationResult>;

package/dist/cjs/operations/cap/validate.js

@@ -0,0 +1,235 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Validation logic for Commerce App Packages (CAPs).
+ *
+ * Performs structural and schema validation of a CAP directory or zip file
+ * without requiring a live B2C instance.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import JSZip from 'jszip';
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/;
+/**
+ * Validates a Commerce App Package (CAP) directory or zip file.
+ *
+ * Checks required files, manifest schema, and cartridge structure rules.
+ * This is a purely local operation — no B2C instance required.
+ *
+ * @param target - Path to a CAP directory or .zip file
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = await validateCap('./my-commerce-app-v1.0.0');
+ * if (!result.valid) {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+export async function validateCap(target) {
+    const errors = [];
+    const warnings = [];
+    let manifest;
+    if (!fs.existsSync(target)) {
+        return { valid: false, errors: [`Target not found: ${target}`], warnings };
+    }
+    const stat = fs.statSync(target);
+    let capDir;
+    let tempDir;
+    if (stat.isDirectory()) {
+        capDir = target;
+    }
+    else if (stat.isFile() && target.endsWith('.zip')) {
+        // Extract zip to temp dir for inspection
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'b2c-cap-validate-'));
+        try {
+            await extractZipToDir(target, tempDir);
+            // The zip root should be a single directory
+            const entries = fs.readdirSync(tempDir);
+            if (entries.length === 1 && fs.statSync(path.join(tempDir, entries[0])).isDirectory()) {
+                capDir = path.join(tempDir, entries[0]);
+            }
+            else {
+                capDir = tempDir;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            cleanupTemp(tempDir);
+            return { valid: false, errors: [`Failed to read zip: ${msg}`], warnings };
+        }
+    }
+    else {
+        return { valid: false, errors: [`Target must be a directory or .zip file: ${target}`], warnings };
+    }
+    try {
+        // --- commerce-app.json ---
+        const manifestPath = path.join(capDir, 'commerce-app.json');
+        if (!fs.existsSync(manifestPath)) {
+            errors.push('Missing required file: commerce-app.json');
+        }
+        else {
+            try {
+                const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                const requiredFields = ['id', 'name', 'version', 'domain'];
+                for (const field of requiredFields) {
+                    if (!raw[field] || typeof raw[field] !== 'string') {
+                        errors.push(`commerce-app.json: missing or invalid field "${field}"`);
+                    }
+                }
+                if (raw.version && typeof raw.version === 'string' && !SEMVER_RE.test(raw.version)) {
+                    errors.push(`commerce-app.json: "version" must be a valid semver string (got "${raw.version}")`);
+                }
+                if (errors.filter((e) => e.startsWith('commerce-app.json:')).length === 0) {
+                    manifest = raw;
+                }
+                // Check root dir naming convention
+                const dirName = path.basename(capDir);
+                if (manifest && dirName !== '.' && dirName !== tempDir) {
+                    const expectedName = `${manifest.id}-v${manifest.version}`;
+                    if (dirName !== expectedName) {
+                        warnings.push(`Root directory "${dirName}" does not match expected convention "${expectedName}"`);
+                    }
+                }
+            }
+            catch {
+                errors.push('commerce-app.json: file exists but is not valid JSON');
+            }
+        }
+        // --- README.md ---
+        if (!fs.existsSync(path.join(capDir, 'README.md'))) {
+            errors.push('Missing required file: README.md');
+        }
+        // --- app-configuration/tasksList.json ---
+        const tasksListPath = path.join(capDir, 'app-configuration', 'tasksList.json');
+        if (!fs.existsSync(tasksListPath)) {
+            errors.push('Missing required file: app-configuration/tasksList.json');
+        }
+        else {
+            try {
+                const tasks = JSON.parse(fs.readFileSync(tasksListPath, 'utf-8'));
+                if (!Array.isArray(tasks)) {
+                    errors.push('app-configuration/tasksList.json: must be a JSON array');
+                }
+                else {
+                    for (let i = 0; i < tasks.length; i++) {
+                        const task = tasks[i];
+                        for (const field of ['taskNumber', 'name', 'description', 'link']) {
+                            if (!task[field]) {
+                                errors.push(`app-configuration/tasksList.json: task[${i}] missing field "${field}"`);
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                errors.push('app-configuration/tasksList.json: file exists but is not valid JSON');
+            }
+        }
+        // --- At least one substantive directory ---
+        const hasCartridges = fs.existsSync(path.join(capDir, 'cartridges'));
+        const hasStorefrontNext = fs.existsSync(path.join(capDir, 'storefront-next'));
+        const hasImpex = fs.existsSync(path.join(capDir, 'impex'));
+        if (!hasCartridges && !hasStorefrontNext && !hasImpex) {
+            errors.push('CAP must contain at least one of: cartridges/, storefront-next/, impex/');
+        }
+        // --- Cartridge rules ---
+        if (hasCartridges) {
+            const cartridgesDir = path.join(capDir, 'cartridges');
+            validateCartridges(cartridgesDir, errors);
+        }
+        // --- Optional warnings ---
+        if (!fs.existsSync(path.join(capDir, 'icons', 'icon.png'))) {
+            warnings.push('icons/icon.png not found (recommended for marketplace listing)');
+        }
+        if (hasImpex && !fs.existsSync(path.join(capDir, 'impex', 'uninstall'))) {
+            warnings.push('impex/uninstall/ not found (recommended for clean removal)');
+        }
+    }
+    finally {
+        cleanupTemp(tempDir);
+    }
+    return { valid: errors.length === 0, errors, warnings, manifest };
+}
+/**
+ * Validates cartridge structure and rules.
+ * - No pipeline/ directories
+ * - No *.ds pipeline descriptor files
+ * - Site cartridges must not have controllers/
+ */
+function validateCartridges(cartridgesDir, errors) {
+    // Check entire cartridges tree for pipelines
+    walkDir(cartridgesDir, (filePath, name, isDir) => {
+        if (isDir && name === 'pipeline') {
+            const rel = path.relative(cartridgesDir, filePath);
+            errors.push(`Pipelines not allowed in CAPs: cartridges/${rel}`);
+        }
+        if (!isDir && name.endsWith('.ds')) {
+            const rel = path.relative(cartridgesDir, filePath);
+            errors.push(`Pipeline descriptor files not allowed in CAPs: cartridges/${rel}`);
+        }
+    });
+    // Site cartridges must not contain controllers/
+    const siteCartridgesDir = path.join(cartridgesDir, 'site_cartridges');
+    if (fs.existsSync(siteCartridgesDir)) {
+        walkDir(siteCartridgesDir, (filePath, name, isDir) => {
+            if (isDir && name === 'controllers') {
+                const rel = path.relative(siteCartridgesDir, filePath);
+                errors.push(`Site cartridges must not contain controllers/ (use BM cartridges instead): site_cartridges/${rel}`);
+            }
+        });
+    }
+}
+/**
+ * Walks a directory tree, calling callback for each entry.
+ * Stops recursing into a directory if callback returns false.
+ */
+function walkDir(dir, cb) {
+    if (!fs.existsSync(dir))
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        cb(fullPath, entry.name, entry.isDirectory());
+        if (entry.isDirectory()) {
+            walkDir(fullPath, cb);
+        }
+    }
+}
+async function extractZipToDir(zipPath, destDir) {
+    const data = await fs.promises.readFile(zipPath);
+    const zip = await JSZip.loadAsync(data);
+    for (const [relPath, entry] of Object.entries(zip.files)) {
+        const fullPath = path.join(destDir, relPath);
+        if (entry.dir) {
+            await fs.promises.mkdir(fullPath, { recursive: true });
+        }
+        else {
+            await fs.promises.mkdir(path.dirname(fullPath), { recursive: true });
+            const content = await entry.async('nodebuffer');
+            await fs.promises.writeFile(fullPath, content);
+        }
+    }
+}
+function cleanupTemp(tempDir) {
+    if (tempDir) {
+        try {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    }
+}
+//# sourceMappingURL=validate.js.map