docs and nit

Author: clavery

packages/b2c-tooling/src/cli/index.ts

@@ -1,3 +1,88 @@
+/**
+ * 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 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)
+ *        └─ MrtCommand (adds MRT API auth)
+ *        └─ OdsCommand (adds ODS config)
+ * ```
+ *
+ * ## Example Usage
+ *
+ * ```typescript
+ * import { InstanceCommand, createTable, type ColumnDef } from '@salesforce/b2c-tooling/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/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/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 type {Flags, Args} from './base-command.js';

packages/b2c-tooling/src/operations/code/watch.ts

@@ -140,7 +140,7 @@ export async function watchCartridges(
 
   logger.debug({count: cartridges.length}, `Watching ${cartridges.length} cartridge(s)`);
   for (const c of cartridges) {
-    logger.debug({cartridge: c.name, path: c.src}, `  ${c.name}`);
+    logger.info({cartridge: c.name, path: c.src}, `  ${c.name}`);
   }
 
   const webdav = instance.webdav;
@@ -196,7 +196,7 @@ export async function watchCartridges(
             const content = await fs.promises.readFile(f.src);
             zip.file(f.dest, content);
           } catch (error) {
-            logger.debug({file: f.src, error}, 'Failed to add file to archive');
+            logger.warn({file: f.src, error}, 'Failed to add file to archive');
           }
         }
 
@@ -248,7 +248,7 @@ export async function watchCartridges(
         const deletePath = `${webdavLocation}/${f.dest}`;
         try {
           await webdav.delete(deletePath);
-          logger.debug({file: deletePath}, `Deleted: ${deletePath}`);
+          logger.info({file: deletePath}, `Deleted: ${deletePath}`);
         } catch (error) {
           logger.debug({file: deletePath, error}, `Failed to delete ${deletePath}`);
         }
@@ -269,7 +269,7 @@ export async function watchCartridges(
 
   watcher.on('all', (event, p) => {
     const fullPath = path.resolve(cwd, p);
-    logger.debug({event, path: fullPath}, `File event: ${event} ${fullPath}`);
+    logger.info({event, path: fullPath}, `File event: ${event} ${fullPath}`);
 
     if (event === 'change' || event === 'add') {
       filesToUpload.add(fullPath);