@salesforce/b2c-tooling-sdk 0.0.1 → 0.0.2

package/dist/esm/cli/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * CLI utilities and base command classes for building B2C Commerce CLI commands.
+ *
+ * This module provides reusable base classes, configuration loading, and table
+ * rendering utilities for oclif-based CLI applications.
+ *
+ * ## Base Command Classes
+ *
+ * Extend these classes to create CLI commands with pre-configured functionality:
+ *
+ * - {@link BaseCommand} - Foundation class with logging, JSON output, and error handling
+ * - {@link OAuthCommand} - Adds OAuth authentication setup
+ * - {@link InstanceCommand} - Adds B2C Commerce instance configuration
+ * - {@link CartridgeCommand} - Adds cartridge path configuration for code operations
+ * - {@link JobCommand} - Adds job execution configuration
+ * - {@link WebDavCommand} - Adds WebDAV root directory configuration for file operations
+ * - {@link MrtCommand} - Adds Managed Runtime API authentication
+ * - {@link OdsCommand} - Adds On-Demand Sandbox configuration
+ *
+ * ## Command Hierarchy
+ *
+ * Commands inherit in a chain, each adding specific functionality:
+ *
+ * ```
+ * BaseCommand
+ *   └─ OAuthCommand (adds OAuth)
+ *        └─ InstanceCommand (adds instance config)
+ *             ├─ CartridgeCommand (adds cartridge paths)
+ *             ├─ JobCommand (adds job config)
+ *             └─ WebDavCommand (adds WebDAV root config)
+ *        └─ MrtCommand (adds MRT API auth)
+ *        └─ OdsCommand (adds ODS config)
+ * ```
+ *
+ * ## Example Usage
+ *
+ * ```typescript
+ * import { InstanceCommand, createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * export default class ListSites extends InstanceCommand {
+ *   static description = 'List all sites on the instance';
+ *
+ *   async run() {
+ *     const client = await this.createOcapiClient();
+ *     const sites = await client.getSites();
+ *
+ *     const columns: Record<string, ColumnDef<Site>> = {
+ *       id: { header: 'ID', get: (s) => s.id },
+ *       name: { header: 'Name', get: (s) => s.display_name },
+ *     };
+ *
+ *     createTable(columns).render(sites, ['id', 'name']);
+ *   }
+ * }
+ * ```
+ *
+ * ## Configuration Loading
+ *
+ * Use {@link loadConfig} to resolve configuration from multiple sources:
+ *
+ * ```typescript
+ * import { loadConfig } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * const config = await loadConfig({
+ *   flags: { hostname: 'example.com' },
+ *   configPath: './dw.json',
+ * });
+ * ```
+ *
+ * ## Table Rendering
+ *
+ * Use {@link createTable} for consistent tabular output:
+ *
+ * ```typescript
+ * import { createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * const columns: Record<string, ColumnDef<Item>> = {
+ *   id: { header: 'ID', get: (item) => item.id },
+ *   status: { header: 'Status', get: (item) => item.status },
+ * };
+ *
+ * createTable(columns).render(items, ['id', 'status']);
+ * ```
+ *
+ * @module cli
+ */
+export { BaseCommand } from './base-command.js';
+export type { Flags, Args } from './base-command.js';
+export { OAuthCommand } from './oauth-command.js';
+export { InstanceCommand } from './instance-command.js';
+export { CartridgeCommand } from './cartridge-command.js';
+export { JobCommand } from './job-command.js';
+export { MrtCommand } from './mrt-command.js';
+export { OdsCommand } from './ods-command.js';
+export { WebDavCommand, WEBDAV_ROOTS, VALID_ROOTS } from './webdav-command.js';
+export type { WebDavRootKey } from './webdav-command.js';
+export { loadConfig, findDwJson } from './config.js';
+export type { LoadConfigOptions, PluginSources } from './config.js';
+export type { ConfigSourcesHookOptions, ConfigSourcesHookResult, ConfigSourcesHook, HttpMiddlewareHookOptions, HttpMiddlewareHookResult, HttpMiddlewareHook, B2COperationType, B2COperationContext, BeforeB2COperationResult, B2COperationResult, AfterB2COperationResult, B2COperationLifecycleProvider, B2COperationLifecycleHookOptions, B2COperationLifecycleHookResult, B2COperationLifecycleHook, } from './hooks.js';
+export { createB2COperationContext, B2CLifecycleRunner } from './hooks.js';
+export {} from './hooks.js';
+export { TableRenderer, createTable } from './table.js';
+export type { ColumnDef, TableRenderOptions } from './table.js';

package/dist/esm/cli/index.js

@@ -0,0 +1,108 @@
+/*
+ * 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
+ */
+/**
+ * CLI utilities and base command classes for building B2C Commerce CLI commands.
+ *
+ * This module provides reusable base classes, configuration loading, and table
+ * rendering utilities for oclif-based CLI applications.
+ *
+ * ## Base Command Classes
+ *
+ * Extend these classes to create CLI commands with pre-configured functionality:
+ *
+ * - {@link BaseCommand} - Foundation class with logging, JSON output, and error handling
+ * - {@link OAuthCommand} - Adds OAuth authentication setup
+ * - {@link InstanceCommand} - Adds B2C Commerce instance configuration
+ * - {@link CartridgeCommand} - Adds cartridge path configuration for code operations
+ * - {@link JobCommand} - Adds job execution configuration
+ * - {@link WebDavCommand} - Adds WebDAV root directory configuration for file operations
+ * - {@link MrtCommand} - Adds Managed Runtime API authentication
+ * - {@link OdsCommand} - Adds On-Demand Sandbox configuration
+ *
+ * ## Command Hierarchy
+ *
+ * Commands inherit in a chain, each adding specific functionality:
+ *
+ * ```
+ * BaseCommand
+ *   └─ OAuthCommand (adds OAuth)
+ *        └─ InstanceCommand (adds instance config)
+ *             ├─ CartridgeCommand (adds cartridge paths)
+ *             ├─ JobCommand (adds job config)
+ *             └─ WebDavCommand (adds WebDAV root config)
+ *        └─ MrtCommand (adds MRT API auth)
+ *        └─ OdsCommand (adds ODS config)
+ * ```
+ *
+ * ## Example Usage
+ *
+ * ```typescript
+ * import { InstanceCommand, createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * export default class ListSites extends InstanceCommand {
+ *   static description = 'List all sites on the instance';
+ *
+ *   async run() {
+ *     const client = await this.createOcapiClient();
+ *     const sites = await client.getSites();
+ *
+ *     const columns: Record<string, ColumnDef<Site>> = {
+ *       id: { header: 'ID', get: (s) => s.id },
+ *       name: { header: 'Name', get: (s) => s.display_name },
+ *     };
+ *
+ *     createTable(columns).render(sites, ['id', 'name']);
+ *   }
+ * }
+ * ```
+ *
+ * ## Configuration Loading
+ *
+ * Use {@link loadConfig} to resolve configuration from multiple sources:
+ *
+ * ```typescript
+ * import { loadConfig } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * const config = await loadConfig({
+ *   flags: { hostname: 'example.com' },
+ *   configPath: './dw.json',
+ * });
+ * ```
+ *
+ * ## Table Rendering
+ *
+ * Use {@link createTable} for consistent tabular output:
+ *
+ * ```typescript
+ * import { createTable, type ColumnDef } from '@salesforce/b2c-tooling-sdk/cli';
+ *
+ * const columns: Record<string, ColumnDef<Item>> = {
+ *   id: { header: 'ID', get: (item) => item.id },
+ *   status: { header: 'Status', get: (item) => item.status },
+ * };
+ *
+ * createTable(columns).render(items, ['id', 'status']);
+ * ```
+ *
+ * @module cli
+ */
+// Base command classes
+export { BaseCommand } from './base-command.js';
+export { OAuthCommand } from './oauth-command.js';
+export { InstanceCommand } from './instance-command.js';
+export { CartridgeCommand } from './cartridge-command.js';
+export { JobCommand } from './job-command.js';
+export { MrtCommand } from './mrt-command.js';
+export { OdsCommand } from './ods-command.js';
+export { WebDavCommand, WEBDAV_ROOTS, VALID_ROOTS } from './webdav-command.js';
+// Config utilities
+export { loadConfig, findDwJson } from './config.js';
+export { createB2COperationContext, B2CLifecycleRunner } from './hooks.js';
+// Re-export module augmentation for @oclif/core Hooks interface
+export {} from './hooks.js';
+// Table rendering utilities
+export { TableRenderer, createTable } from './table.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAEH,uBAAuB;AACvB,OAAO,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAC,aAAa,EAAE,YAAY,EAAE,WAAW,EAAC,MAAM,qBAAqB,CAAC;AAG7E,mBAAmB;AACnB,OAAO,EAAC,UAAU,EAAE,UAAU,EAAC,MAAM,aAAa,CAAC;AAsBnD,OAAO,EAAC,yBAAyB,EAAE,kBAAkB,EAAC,MAAM,YAAY,CAAC;AACzE,gEAAgE;AAChE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,4BAA4B;AAC5B,OAAO,EAAC,aAAa,EAAE,WAAW,EAAC,MAAM,YAAY,CAAC"}

package/dist/esm/cli/instance-command.d.ts

@@ -0,0 +1,121 @@
+import { Command } from '@oclif/core';
+import { OAuthCommand } from './oauth-command.js';
+import type { ResolvedB2CConfig } from '../config/index.js';
+import type { B2CInstance } from '../instance/index.js';
+import { B2CLifecycleRunner, type B2COperationType, type B2COperationContext, type B2COperationResult, type BeforeB2COperationResult } from './lifecycle.js';
+/**
+ * Base command for B2C instance operations.
+ * Use this for commands that interact with a specific B2C instance
+ * (sites, code upload, jobs, etc.)
+ *
+ * Environment variables:
+ * - SFCC_SERVER: B2C instance hostname
+ * - SFCC_WEBDAV_SERVER: Separate WebDAV hostname (optional)
+ * - SFCC_CODE_VERSION: Code version
+ * - SFCC_USERNAME: Username for Basic Auth
+ * - SFCC_PASSWORD: Password/access key for Basic Auth
+ * - Plus all from OAuthCommand (SFCC_CLIENT_ID, SFCC_CLIENT_SECRET)
+ *
+ * Provides:
+ * - Server/hostname connection flags
+ * - Both Basic auth and OAuth support
+ * - Unified B2CInstance with typed API clients
+ *
+ * @example
+ * export default class MySiteCommand extends InstanceCommand<typeof MySiteCommand> {
+ *   async run(): Promise<void> {
+ *     // Single instance for all operations
+ *     const { data } = await this.instance.ocapi.GET('/sites', {});
+ *     await this.instance.webdav.mkcol('Cartridges/v1');
+ *   }
+ * }
+ */
+export declare abstract class InstanceCommand<T extends typeof Command> extends OAuthCommand<T> {
+    static baseFlags: {
+        server: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'webdav-server': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'code-version': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        username: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        password: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'client-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'client-secret': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        scope: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'short-code': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'auth-methods': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'account-manager-host': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'log-level': import("@oclif/core/interfaces").OptionFlag<"trace" | "debug" | "info" | "warn" | "error" | "silent" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        debug: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        lang: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'working-directory': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'extra-query': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'extra-body': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'extra-headers': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    private _instance?;
+    /** Lifecycle runner for B2C operation hooks */
+    protected lifecycleRunner?: B2CLifecycleRunner;
+    /**
+     * Override init to collect lifecycle providers from plugins.
+     */
+    init(): Promise<void>;
+    /**
+     * Collects lifecycle providers from plugins via the `b2c:operation-lifecycle` hook.
+     */
+    protected collectLifecycleProviders(): Promise<void>;
+    /**
+     * Creates a B2C operation context for lifecycle hooks.
+     *
+     * @param operationType - Type of B2C operation
+     * @param metadata - Operation-specific metadata
+     * @returns B2C operation context
+     */
+    protected createContext(operationType: B2COperationType, metadata: Record<string, unknown>): B2COperationContext;
+    /**
+     * Runs beforeOperation hooks for all providers.
+     *
+     * @param context - B2C operation context
+     * @returns Result indicating if operation should be skipped
+     */
+    protected runBeforeHooks(context: B2COperationContext): Promise<BeforeB2COperationResult>;
+    /**
+     * Runs afterOperation hooks for all providers.
+     *
+     * @param context - B2C operation context
+     * @param result - Operation result
+     */
+    protected runAfterHooks(context: B2COperationContext, result: B2COperationResult): Promise<void>;
+    protected loadConfiguration(): ResolvedB2CConfig;
+    /**
+     * Gets the B2CInstance for this command.
+     *
+     * The instance is lazily created from the resolved configuration.
+     * It provides typed API clients for WebDAV and OCAPI operations.
+     *
+     * @example
+     * // WebDAV operations (uses Basic auth if available)
+     * await this.instance.webdav.mkcol('Cartridges/v1');
+     *
+     * // OCAPI operations (uses OAuth)
+     * const { data } = await this.instance.ocapi.GET('/sites', {});
+     */
+    protected get instance(): B2CInstance;
+    /**
+     * Check if WebDAV credentials are available (Basic or OAuth including implicit).
+     */
+    protected hasWebDavCredentials(): boolean;
+    /**
+     * Validates that server is configured, errors if not.
+     */
+    protected requireServer(): void;
+    /**
+     * Validates that code version is configured, errors if not.
+     */
+    protected requireCodeVersion(): void;
+    /**
+     * Validates that WebDAV credentials are configured, errors if not.
+     */
+    protected requireWebDavCredentials(): void;
+}

package/dist/esm/cli/instance-command.js

@@ -0,0 +1,213 @@
+/*
+ * 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 { Command, Flags } from '@oclif/core';
+import { OAuthCommand } from './oauth-command.js';
+import { loadConfig } from './config.js';
+import { t } from '../i18n/index.js';
+import { B2CLifecycleRunner, createB2COperationContext, } from './lifecycle.js';
+/**
+ * Base command for B2C instance operations.
+ * Use this for commands that interact with a specific B2C instance
+ * (sites, code upload, jobs, etc.)
+ *
+ * Environment variables:
+ * - SFCC_SERVER: B2C instance hostname
+ * - SFCC_WEBDAV_SERVER: Separate WebDAV hostname (optional)
+ * - SFCC_CODE_VERSION: Code version
+ * - SFCC_USERNAME: Username for Basic Auth
+ * - SFCC_PASSWORD: Password/access key for Basic Auth
+ * - Plus all from OAuthCommand (SFCC_CLIENT_ID, SFCC_CLIENT_SECRET)
+ *
+ * Provides:
+ * - Server/hostname connection flags
+ * - Both Basic auth and OAuth support
+ * - Unified B2CInstance with typed API clients
+ *
+ * @example
+ * export default class MySiteCommand extends InstanceCommand<typeof MySiteCommand> {
+ *   async run(): Promise<void> {
+ *     // Single instance for all operations
+ *     const { data } = await this.instance.ocapi.GET('/sites', {});
+ *     await this.instance.webdav.mkcol('Cartridges/v1');
+ *   }
+ * }
+ */
+export class InstanceCommand extends OAuthCommand {
+    static baseFlags = {
+        ...OAuthCommand.baseFlags,
+        server: Flags.string({
+            char: 's',
+            description: 'B2C instance hostname',
+            env: 'SFCC_SERVER',
+            helpGroup: 'INSTANCE',
+        }),
+        'webdav-server': Flags.string({
+            description: 'Separate hostname for WebDAV (cert. hostname, etc)',
+            env: 'SFCC_WEBDAV_SERVER',
+            helpGroup: 'INSTANCE',
+        }),
+        'code-version': Flags.string({
+            char: 'v',
+            description: 'Code version',
+            env: 'SFCC_CODE_VERSION',
+            helpGroup: 'INSTANCE',
+        }),
+        username: Flags.string({
+            char: 'u',
+            description: 'Username for Basic Auth (WebDAV)',
+            env: 'SFCC_USERNAME',
+            helpGroup: 'AUTH',
+        }),
+        password: Flags.string({
+            char: 'p',
+            description: 'Password/access key for Basic Auth (WebDAV)',
+            env: 'SFCC_PASSWORD',
+            helpGroup: 'AUTH',
+        }),
+    };
+    _instance;
+    /** Lifecycle runner for B2C operation hooks */
+    lifecycleRunner;
+    /**
+     * Override init to collect lifecycle providers from plugins.
+     */
+    async init() {
+        await super.init();
+        await this.collectLifecycleProviders();
+    }
+    /**
+     * Collects lifecycle providers from plugins via the `b2c:operation-lifecycle` hook.
+     */
+    async collectLifecycleProviders() {
+        this.lifecycleRunner = new B2CLifecycleRunner(this.logger);
+        const hookOptions = {
+            flags: this.flags,
+        };
+        const hookResult = await this.config.runHook('b2c:operation-lifecycle', hookOptions);
+        for (const success of hookResult.successes) {
+            const result = success.result;
+            if (!result?.providers?.length)
+                continue;
+            this.lifecycleRunner.addProviders(result.providers);
+        }
+        for (const failure of hookResult.failures) {
+            this.logger?.warn(`Plugin ${failure.plugin.name} b2c:operation-lifecycle hook failed: ${failure.error.message}`);
+        }
+        if (this.lifecycleRunner.size > 0) {
+            this.logger?.debug(`Registered ${this.lifecycleRunner.size} lifecycle provider(s)`);
+        }
+    }
+    /**
+     * Creates a B2C operation context for lifecycle hooks.
+     *
+     * @param operationType - Type of B2C operation
+     * @param metadata - Operation-specific metadata
+     * @returns B2C operation context
+     */
+    createContext(operationType, metadata) {
+        return createB2COperationContext(operationType, metadata, this.instance);
+    }
+    /**
+     * Runs beforeOperation hooks for all providers.
+     *
+     * @param context - B2C operation context
+     * @returns Result indicating if operation should be skipped
+     */
+    async runBeforeHooks(context) {
+        if (!this.lifecycleRunner) {
+            return {};
+        }
+        return this.lifecycleRunner.runBefore(context);
+    }
+    /**
+     * Runs afterOperation hooks for all providers.
+     *
+     * @param context - B2C operation context
+     * @param result - Operation result
+     */
+    async runAfterHooks(context, result) {
+        if (!this.lifecycleRunner) {
+            return;
+        }
+        await this.lifecycleRunner.runAfter(context, result);
+    }
+    loadConfiguration() {
+        const options = {
+            instance: this.flags.instance,
+            configPath: this.flags.config,
+        };
+        const flagConfig = {
+            hostname: this.flags.server,
+            webdavHostname: this.flags['webdav-server'],
+            codeVersion: this.flags['code-version'],
+            username: this.flags.username,
+            password: this.flags.password,
+            clientId: this.flags['client-id'],
+            clientSecret: this.flags['client-secret'],
+            authMethods: this.parseAuthMethods(),
+            accountManagerHost: this.flags['account-manager-host'],
+            // Merge scopes from flags (if provided)
+            scopes: this.flags.scope && this.flags.scope.length > 0 ? this.flags.scope : undefined,
+        };
+        const pluginSources = {
+            before: this.pluginSourcesBefore,
+            after: this.pluginSourcesAfter,
+        };
+        return loadConfig(flagConfig, options, pluginSources);
+    }
+    /**
+     * Gets the B2CInstance for this command.
+     *
+     * The instance is lazily created from the resolved configuration.
+     * It provides typed API clients for WebDAV and OCAPI operations.
+     *
+     * @example
+     * // WebDAV operations (uses Basic auth if available)
+     * await this.instance.webdav.mkcol('Cartridges/v1');
+     *
+     * // OCAPI operations (uses OAuth)
+     * const { data } = await this.instance.ocapi.GET('/sites', {});
+     */
+    get instance() {
+        if (!this._instance) {
+            this.requireServer();
+            this._instance = this.resolvedConfig.createB2CInstance();
+        }
+        return this._instance;
+    }
+    /**
+     * Check if WebDAV credentials are available (Basic or OAuth including implicit).
+     */
+    hasWebDavCredentials() {
+        // Basic auth, or OAuth (client-credentials needs secret, implicit only needs clientId)
+        return this.resolvedConfig.hasBasicAuthConfig() || this.resolvedConfig.hasOAuthConfig();
+    }
+    /**
+     * Validates that server is configured, errors if not.
+     */
+    requireServer() {
+        if (!this.resolvedConfig.hasB2CInstanceConfig()) {
+            this.error(t('error.serverRequired', 'Server is required. Set via --server, SFCC_SERVER env var, or dw.json.'));
+        }
+    }
+    /**
+     * Validates that code version is configured, errors if not.
+     */
+    requireCodeVersion() {
+        if (!this.resolvedConfig.values.codeVersion) {
+            this.error(t('error.codeVersionRequired', 'Code version is required. Set via --code-version, SFCC_CODE_VERSION env var, or dw.json.'));
+        }
+    }
+    /**
+     * Validates that WebDAV credentials are configured, errors if not.
+     */
+    requireWebDavCredentials() {
+        if (!this.hasWebDavCredentials()) {
+            this.error(t('error.webdavCredentialsRequiredShort', 'WebDAV credentials required. Provide --username/--password or --client-id/--client-secret, or set corresponding SFCC_* env vars.'));
+        }
+    }
+}
+//# sourceMappingURL=instance-command.js.map

package/dist/esm/cli/instance-command.js.map

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

package/dist/esm/cli/job-command.d.ts

@@ -0,0 +1,32 @@
+import { Command } from '@oclif/core';
+import { InstanceCommand } from './instance-command.js';
+import { type JobExecution } from '../operations/jobs/index.js';
+/**
+ * Base command for job operations.
+ *
+ * Extends InstanceCommand with job-specific functionality like
+ * displaying job logs on failure.
+ *
+ * @example
+ * export default class MyJobCommand extends JobCommand<typeof MyJobCommand> {
+ *   async run(): Promise<void> {
+ *     try {
+ *       await executeJob(this.instance, 'my-job');
+ *     } catch (error) {
+ *       if (error instanceof JobExecutionError) {
+ *         await this.showJobLog(error.execution);
+ *       }
+ *       throw error;
+ *     }
+ *   }
+ * }
+ */
+export declare abstract class JobCommand<T extends typeof Command> extends InstanceCommand<T> {
+    /**
+     * Display a job's log file content and error message if available.
+     * Outputs to stderr since this is typically shown for failed jobs.
+     *
+     * @param execution - Job execution with log file info
+     */
+    protected showJobLog(execution: JobExecution): Promise<void>;
+}

package/dist/esm/cli/job-command.js

@@ -0,0 +1,66 @@
+/*
+ * 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 { Command } from '@oclif/core';
+import { InstanceCommand } from './instance-command.js';
+import { getJobLog, getJobErrorMessage } from '../operations/jobs/index.js';
+import { t } from '../i18n/index.js';
+/**
+ * Base command for job operations.
+ *
+ * Extends InstanceCommand with job-specific functionality like
+ * displaying job logs on failure.
+ *
+ * @example
+ * export default class MyJobCommand extends JobCommand<typeof MyJobCommand> {
+ *   async run(): Promise<void> {
+ *     try {
+ *       await executeJob(this.instance, 'my-job');
+ *     } catch (error) {
+ *       if (error instanceof JobExecutionError) {
+ *         await this.showJobLog(error.execution);
+ *       }
+ *       throw error;
+ *     }
+ *   }
+ * }
+ */
+export class JobCommand extends InstanceCommand {
+    /**
+     * Display a job's log file content and error message if available.
+     * Outputs to stderr since this is typically shown for failed jobs.
+     *
+     * @param execution - Job execution with log file info
+     */
+    async showJobLog(execution) {
+        // Extract error message from failed step executions
+        const errorMessage = getJobErrorMessage(execution);
+        if (!execution.is_log_file_existing) {
+            // No log file, but we may still have an error message
+            if (errorMessage) {
+                this.logger.error({ errorMessage }, errorMessage);
+            }
+            return;
+        }
+        try {
+            const log = await getJobLog(this.instance, execution);
+            const logFileName = execution.log_file_path?.split('/').pop() ?? 'job.log';
+            const header = t('cli.job.logHeader', 'Job log ({{logFileName}}):', { logFileName });
+            this.logger.error({ log, errorMessage }, `${header}\n${log}`);
+            // Log the error message separately if available
+            if (errorMessage) {
+                this.logger.error(t('cli.job.errorMessage', 'Error: {{message}}', { message: errorMessage }));
+            }
+        }
+        catch {
+            this.warn(t('cli.job.logFetchFailed', 'Could not retrieve job log'));
+            // Still try to show error message even if log fetch failed
+            if (errorMessage) {
+                this.logger.error({ errorMessage }, errorMessage);
+            }
+        }
+    }
+}
+//# sourceMappingURL=job-command.js.map

package/dist/esm/cli/job-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-command.js","sourceRoot":"","sources":["../../../src/cli/job-command.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,OAAO,EAAC,MAAM,aAAa,CAAC;AACpC,OAAO,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAC,SAAS,EAAE,kBAAkB,EAAoB,MAAM,6BAA6B,CAAC;AAC7F,OAAO,EAAC,CAAC,EAAC,MAAM,kBAAkB,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAgB,UAAqC,SAAQ,eAAkB;IACnF;;;;;OAKG;IACO,KAAK,CAAC,UAAU,CAAC,SAAuB;QAChD,oDAAoD;QACpD,MAAM,YAAY,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;QAEnD,IAAI,CAAC,SAAS,CAAC,oBAAoB,EAAE,CAAC;YACpC,sDAAsD;YACtD,IAAI,YAAY,EAAE,CAAC;gBACjB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAC,YAAY,EAAC,EAAE,YAAY,CAAC,CAAC;YAClD,CAAC;YACD,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YACtD,MAAM,WAAW,GAAG,SAAS,CAAC,aAAa,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,SAAS,CAAC;YAE3E,MAAM,MAAM,GAAG,CAAC,CAAC,mBAAmB,EAAE,4BAA4B,EAAE,EAAC,WAAW,EAAC,CAAC,CAAC;YACnF,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAC,GAAG,EAAE,YAAY,EAAC,EAAE,GAAG,MAAM,KAAK,GAAG,EAAE,CAAC,CAAC;YAE5D,gDAAgD;YAChD,IAAI,YAAY,EAAE,CAAC;gBACjB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,sBAAsB,EAAE,oBAAoB,EAAE,EAAC,OAAO,EAAE,YAAY,EAAC,CAAC,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,wBAAwB,EAAE,4BAA4B,CAAC,CAAC,CAAC;YACrE,2DAA2D;YAC3D,IAAI,YAAY,EAAE,CAAC;gBACjB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAC,YAAY,EAAC,EAAE,YAAY,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;IACH,CAAC;CACF"}