ultravisor-beacon-capability 1.0.0

package/docs/examples/docker-container-management.md

@@ -0,0 +1,265 @@
+# Example: Docker Container Management
+
+A capability for listing, restarting, and pruning Docker containers and images. Wraps Docker CLI commands as beacon actions for remote orchestration through Ultravisor.
+
+## Full Source
+
+```javascript
+const libFable = require('fable');
+const libBeaconCapability = require('ultravisor-beacon-capability');
+const libChildProcess = require('child_process');
+
+class DockerManagement extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'DockerManagement';
+		this.capabilityName = 'DockerManagement';
+	}
+
+	/**
+	 * Internal: run a docker command and return the output.
+	 */
+	_exec(pCmd, pTimeout, fCallback)
+	{
+		libChildProcess.exec(pCmd, { timeout: pTimeout || 60000, maxBuffer: 5 * 1024 * 1024 }, (pError, pStdOut, pStdErr) =>
+		{
+			if (pError)
+			{
+				return fCallback(new Error(`${pCmd}: ${pStdErr || pError.message}`));
+			}
+			return fCallback(null, pStdOut.trim());
+		});
+	}
+
+	// --- Action: ListContainers ---
+
+	get actionListContainers_Description()
+	{
+		return 'List Docker containers with status, ports, and resource usage';
+	}
+
+	get actionListContainers_Schema()
+	{
+		return [
+			{ Name: 'All', DataType: 'Boolean', Required: false, Default: false, Description: 'Include stopped containers' },
+			{ Name: 'Filter', DataType: 'String', Required: false, Description: 'Docker filter expression (e.g. "status=running")' }
+		];
+	}
+
+	actionListContainers(pSettings, pWorkItem, fCallback)
+	{
+		let tmpFlags = pSettings.All ? '-a' : '';
+		let tmpFilter = pSettings.Filter ? `--filter "${pSettings.Filter}"` : '';
+		let tmpFormat = '{{.ID}}\\t{{.Names}}\\t{{.Image}}\\t{{.Status}}\\t{{.Ports}}\\t{{.Size}}';
+
+		let tmpCmd = `docker ps ${tmpFlags} ${tmpFilter} --format '${tmpFormat}' --size`;
+
+		this._exec(tmpCmd, 30000, (pError, pOutput) =>
+		{
+			if (pError) return fCallback(pError);
+
+			let tmpContainers = pOutput.split('\n').filter(Boolean).map((pLine) =>
+			{
+				let tmpParts = pLine.split('\t');
+				return {
+					ID: tmpParts[0],
+					Name: tmpParts[1],
+					Image: tmpParts[2],
+					Status: tmpParts[3],
+					Ports: tmpParts[4],
+					Size: tmpParts[5]
+				};
+			});
+
+			return fCallback(null, {
+				Outputs: { Containers: tmpContainers, Count: tmpContainers.length },
+				Log: [`Found ${tmpContainers.length} containers`]
+			});
+		});
+	}
+
+	// --- Action: RestartContainer ---
+
+	get actionRestartContainer_Description()
+	{
+		return 'Restart a Docker container by name or ID';
+	}
+
+	get actionRestartContainer_Schema()
+	{
+		return [
+			{ Name: 'Container', DataType: 'String', Required: true, Description: 'Container name or ID' },
+			{ Name: 'TimeoutSeconds', DataType: 'Integer', Required: false, Default: 10 }
+		];
+	}
+
+	actionRestartContainer(pSettings, pWorkItem, fCallback)
+	{
+		let tmpTimeout = parseInt(pSettings.TimeoutSeconds, 10) || 10;
+		let tmpCmd = `docker restart --time ${tmpTimeout} ${pSettings.Container}`;
+
+		this.log.info(`Restarting container: ${pSettings.Container}`);
+
+		this._exec(tmpCmd, 120000, (pError, pOutput) =>
+		{
+			if (pError) return fCallback(pError);
+
+			// Verify it's running
+			this._exec(`docker inspect --format '{{.State.Status}}' ${pSettings.Container}`, 10000, (pInspectError, pStatus) =>
+			{
+				return fCallback(null, {
+					Outputs: {
+						Container: pSettings.Container,
+						Status: pStatus || 'unknown',
+						Restarted: true
+					},
+					Log: [`Restarted ${pSettings.Container}, status: ${pStatus || 'unknown'}`]
+				});
+			});
+		});
+	}
+
+	// --- Action: PruneSystem ---
+
+	get actionPruneSystem_Description()
+	{
+		return 'Remove unused containers, images, networks, and volumes';
+	}
+
+	get actionPruneSystem_Schema()
+	{
+		return [
+			{ Name: 'Volumes', DataType: 'Boolean', Required: false, Default: false, Description: 'Also prune unused volumes' },
+			{ Name: 'OlderThanHours', DataType: 'Integer', Required: false, Description: 'Only prune resources older than N hours' }
+		];
+	}
+
+	actionPruneSystem(pSettings, pWorkItem, fCallback, fReportProgress)
+	{
+		let tmpFilter = pSettings.OlderThanHours ? `--filter "until=${pSettings.OlderThanHours}h"` : '';
+		let tmpVolumes = pSettings.Volumes ? '--volumes' : '';
+		let tmpResults = {};
+
+		fReportProgress({ Percent: 10, Message: 'Pruning containers...' });
+
+		// Prune stopped containers
+		this._exec(`docker container prune -f ${tmpFilter}`, 60000, (pContainerError, pContainerOut) =>
+		{
+			tmpResults.ContainerPrune = pContainerOut || (pContainerError ? pContainerError.message : 'done');
+
+			fReportProgress({ Percent: 30, Message: 'Pruning images...' });
+
+			// Prune dangling images
+			this._exec(`docker image prune -f ${tmpFilter}`, 120000, (pImageError, pImageOut) =>
+			{
+				tmpResults.ImagePrune = pImageOut || (pImageError ? pImageError.message : 'done');
+
+				fReportProgress({ Percent: 60, Message: 'Pruning networks...' });
+
+				// Prune networks
+				this._exec(`docker network prune -f ${tmpFilter}`, 30000, (pNetError, pNetOut) =>
+				{
+					tmpResults.NetworkPrune = pNetOut || (pNetError ? pNetError.message : 'done');
+
+					if (pSettings.Volumes)
+					{
+						fReportProgress({ Percent: 80, Message: 'Pruning volumes...' });
+
+						this._exec('docker volume prune -f', 60000, (pVolError, pVolOut) =>
+						{
+							tmpResults.VolumePrune = pVolOut || (pVolError ? pVolError.message : 'done');
+
+							return fCallback(null, {
+								Outputs: tmpResults,
+								Log: ['Docker system prune complete (including volumes)']
+							});
+						});
+					}
+					else
+					{
+						return fCallback(null, {
+							Outputs: tmpResults,
+							Log: ['Docker system prune complete (volumes skipped)']
+						});
+					}
+				});
+			});
+		});
+	}
+
+	// --- Action: ContainerLogs ---
+
+	get actionContainerLogs_Description()
+	{
+		return 'Retrieve recent logs from a Docker container';
+	}
+
+	get actionContainerLogs_Schema()
+	{
+		return [
+			{ Name: 'Container', DataType: 'String', Required: true },
+			{ Name: 'TailLines', DataType: 'Integer', Required: false, Default: 100 },
+			{ Name: 'Since', DataType: 'String', Required: false, Description: 'Show logs since timestamp or relative (e.g. "1h", "2024-01-01")' }
+		];
+	}
+
+	actionContainerLogs(pSettings, pWorkItem, fCallback)
+	{
+		let tmpTail = parseInt(pSettings.TailLines, 10) || 100;
+		let tmpSince = pSettings.Since ? `--since ${pSettings.Since}` : '';
+
+		let tmpCmd = `docker logs --tail ${tmpTail} ${tmpSince} ${pSettings.Container} 2>&1`;
+
+		this._exec(tmpCmd, 30000, (pError, pOutput) =>
+		{
+			if (pError) return fCallback(pError);
+			return fCallback(null, {
+				Outputs: {
+					Container: pSettings.Container,
+					Logs: pOutput,
+					LineCount: pOutput.split('\n').length
+				},
+				Log: [`Retrieved ${tmpTail} tail lines from ${pSettings.Container}`]
+			});
+		});
+	}
+}
+
+// --- Startup ---
+
+let tmpFable = new libFable({ Product: 'DockerManagement', ProductVersion: '1.0.0' });
+tmpFable.addServiceType('DockerManagement', DockerManagement);
+let tmpCap = tmpFable.instantiateServiceProvider('DockerManagement');
+
+tmpCap.connect(
+	{
+		ServerURL: process.env.ULTRAVISOR_URL || 'http://localhost:54321',
+		Name: `docker-mgmt-${require('os').hostname()}`,
+		MaxConcurrent: 2
+	},
+	(pError) =>
+	{
+		if (pError) throw pError;
+		console.log('Docker management beacon online');
+	});
+
+process.on('SIGTERM', () => { tmpCap.disconnect(() => process.exit(0)); });
+```
+
+## Registered Task Types
+
+- `beacon-dockermanagement-listcontainers`
+- `beacon-dockermanagement-restartcontainer`
+- `beacon-dockermanagement-prunesystem`
+- `beacon-dockermanagement-containerlogs`
+
+## Key Points
+
+- **Wraps Docker CLI** -- requires `docker` to be available on the host
+- **RestartContainer** verifies the container is running after restart
+- **PruneSystem** is sequential (containers -> images -> networks -> volumes) with progress reporting
+- **OlderThanHours** filter prevents pruning of recently used resources
+- **ContainerLogs** captures both stdout and stderr via `2>&1`
+- Useful for managing Docker hosts where you want centralized visibility and control through Ultravisor

package/docs/examples/log-archive-and-upload.md

@@ -0,0 +1,214 @@
+# Example: Log Archive and Upload
+
+A capability that compresses log directories into tar.gz archives and optionally uploads them to S3. Useful for archiving logs before cleanup or for centralized log storage.
+
+## Full Source
+
+```javascript
+const libFable = require('fable');
+const libBeaconCapability = require('ultravisor-beacon-capability');
+const libChildProcess = require('child_process');
+const libPath = require('path');
+const libFS = require('fs');
+
+class LogArchive extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'LogArchive';
+		this.capabilityName = 'LogArchive';
+	}
+
+	// --- Action: CompressLogs ---
+
+	get actionCompressLogs_Description()
+	{
+		return 'Compress a log directory into a timestamped tar.gz archive';
+	}
+
+	get actionCompressLogs_Schema()
+	{
+		return [
+			{ Name: 'SourceDirectory', DataType: 'String', Required: true },
+			{ Name: 'OutputDirectory', DataType: 'String', Required: true },
+			{ Name: 'ArchivePrefix', DataType: 'String', Required: false, Default: 'logs' },
+			{ Name: 'Pattern', DataType: 'String', Required: false, Default: '*.log', Description: 'File pattern to include' },
+			{ Name: 'OlderThanDays', DataType: 'Integer', Required: false, Description: 'Only archive files older than N days' },
+			{ Name: 'DeleteOriginals', DataType: 'Boolean', Required: false, Default: false }
+		];
+	}
+
+	actionCompressLogs(pSettings, pWorkItem, fCallback, fReportProgress)
+	{
+		let tmpTimestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
+		let tmpArchiveName = `${pSettings.ArchivePrefix || 'logs'}-${tmpTimestamp}.tar.gz`;
+		let tmpOutputPath = libPath.join(pSettings.OutputDirectory, tmpArchiveName);
+
+		// Build the find command to collect files
+		let tmpFindCmd = `find ${pSettings.SourceDirectory} -name '${pSettings.Pattern || '*.log'}' -type f`;
+		if (pSettings.OlderThanDays)
+		{
+			tmpFindCmd += ` -mtime +${pSettings.OlderThanDays}`;
+		}
+
+		fReportProgress({ Percent: 10, Message: 'Scanning for files to archive...' });
+
+		// Count files first
+		libChildProcess.exec(`${tmpFindCmd} | wc -l`, (pCountError, pCountOut) =>
+		{
+			if (pCountError) return fCallback(pCountError);
+
+			let tmpFileCount = parseInt(pCountOut.trim(), 10);
+			if (tmpFileCount === 0)
+			{
+				return fCallback(null, {
+					Outputs: { FileCount: 0, ArchivePath: null },
+					Log: ['No files matched the criteria']
+				});
+			}
+
+			fReportProgress({ Percent: 20, Message: `Found ${tmpFileCount} files, compressing...` });
+
+			// Create the archive
+			let tmpTarCmd = `${tmpFindCmd} | tar -czf ${tmpOutputPath} -T -`;
+
+			libChildProcess.exec(tmpTarCmd, { timeout: 600000 }, (pTarError) =>
+			{
+				if (pTarError) return fCallback(pTarError);
+
+				fReportProgress({ Percent: 70, Message: 'Archive created, checking size...' });
+
+				// Get archive size
+				libFS.stat(tmpOutputPath, (pStatError, pStats) =>
+				{
+					if (pStatError) return fCallback(pStatError);
+
+					let tmpSizeMB = (pStats.size / (1024 * 1024)).toFixed(2);
+
+					if (pSettings.DeleteOriginals)
+					{
+						fReportProgress({ Percent: 80, Message: 'Deleting original files...' });
+						libChildProcess.exec(`${tmpFindCmd} -delete`, (pDelError) =>
+						{
+							if (pDelError) this.log.warn(`Delete error: ${pDelError.message}`);
+
+							return fCallback(null, {
+								Outputs: {
+									ArchivePath: tmpOutputPath,
+									ArchiveName: tmpArchiveName,
+									ArchiveSizeMB: parseFloat(tmpSizeMB),
+									FileCount: tmpFileCount,
+									OriginalsDeleted: true
+								},
+								Log: [`Archived ${tmpFileCount} files to ${tmpArchiveName} (${tmpSizeMB}MB), originals deleted`]
+							});
+						});
+					}
+					else
+					{
+						return fCallback(null, {
+							Outputs: {
+								ArchivePath: tmpOutputPath,
+								ArchiveName: tmpArchiveName,
+								ArchiveSizeMB: parseFloat(tmpSizeMB),
+								FileCount: tmpFileCount,
+								OriginalsDeleted: false
+							},
+							Log: [`Archived ${tmpFileCount} files to ${tmpArchiveName} (${tmpSizeMB}MB)`]
+						});
+					}
+				});
+			});
+		});
+	}
+
+	// --- Action: UploadToS3 ---
+
+	get actionUploadToS3_Description()
+	{
+		return 'Upload a file to an S3 bucket using the AWS CLI';
+	}
+
+	get actionUploadToS3_Schema()
+	{
+		return [
+			{ Name: 'FilePath', DataType: 'String', Required: true },
+			{ Name: 'Bucket', DataType: 'String', Required: true },
+			{ Name: 'Prefix', DataType: 'String', Required: false, Default: 'logs/' },
+			{ Name: 'StorageClass', DataType: 'String', Required: false, Default: 'STANDARD_IA' },
+			{ Name: 'DeleteAfterUpload', DataType: 'Boolean', Required: false, Default: false }
+		];
+	}
+
+	actionUploadToS3(pSettings, pWorkItem, fCallback, fReportProgress)
+	{
+		let tmpFileName = libPath.basename(pSettings.FilePath);
+		let tmpS3Key = `${pSettings.Prefix || 'logs/'}${tmpFileName}`;
+		let tmpS3URI = `s3://${pSettings.Bucket}/${tmpS3Key}`;
+
+		fReportProgress({ Percent: 10, Message: `Uploading to ${tmpS3URI}...` });
+
+		let tmpCmd = `aws s3 cp ${pSettings.FilePath} ${tmpS3URI} --storage-class ${pSettings.StorageClass || 'STANDARD_IA'}`;
+
+		libChildProcess.exec(tmpCmd, { timeout: 600000 }, (pUploadError, pStdOut) =>
+		{
+			if (pUploadError) return fCallback(pUploadError);
+
+			fReportProgress({ Percent: 90, Message: 'Upload complete' });
+
+			if (pSettings.DeleteAfterUpload)
+			{
+				libFS.unlink(pSettings.FilePath, (pUnlinkError) =>
+				{
+					if (pUnlinkError) this.log.warn(`Could not delete ${pSettings.FilePath}: ${pUnlinkError.message}`);
+
+					return fCallback(null, {
+						Outputs: { S3URI: tmpS3URI, LocalDeleted: !pUnlinkError },
+						Log: [`Uploaded ${tmpFileName} to ${tmpS3URI}, local file deleted`]
+					});
+				});
+			}
+			else
+			{
+				return fCallback(null, {
+					Outputs: { S3URI: tmpS3URI, LocalDeleted: false },
+					Log: [`Uploaded ${tmpFileName} to ${tmpS3URI}`]
+				});
+			}
+		});
+	}
+}
+
+// --- Startup ---
+
+let tmpFable = new libFable({ Product: 'LogArchive', ProductVersion: '1.0.0' });
+tmpFable.addServiceType('LogArchive', LogArchive);
+let tmpCap = tmpFable.instantiateServiceProvider('LogArchive');
+
+tmpCap.connect(
+	{
+		ServerURL: process.env.ULTRAVISOR_URL || 'http://localhost:54321',
+		Name: `log-archive-${require('os').hostname()}`
+	},
+	(pError) =>
+	{
+		if (pError) throw pError;
+		console.log('Log archive beacon online');
+	});
+
+process.on('SIGTERM', () => { tmpCap.disconnect(() => process.exit(0)); });
+```
+
+## Registered Task Types
+
+- `beacon-logarchive-compresslogs`
+- `beacon-logarchive-uploadtos3`
+
+## Key Points
+
+- **CompressLogs** and **UploadToS3** can be composed into an operation graph: compress first, then upload
+- **Timestamped archive names** prevent collisions
+- **OlderThanDays** filter lets you archive only stale logs while leaving recent ones in place
+- **StorageClass** defaults to `STANDARD_IA` for cost-effective long-term storage
+- The S3 upload uses the AWS CLI, so credentials must be configured on the host (environment variables or IAM role)

package/docs/examples/log-file-cleanup.md

@@ -0,0 +1,199 @@
+# Example: Log File Cleanup
+
+A capability for finding and deleting old log files by age and size. Replaces the cron-job-plus-bash-script pattern with observable, auditable cleanup operations.
+
+## Full Source
+
+```javascript
+const libFable = require('fable');
+const libBeaconCapability = require('ultravisor-beacon-capability');
+const libChildProcess = require('child_process');
+const libFS = require('fs');
+const libPath = require('path');
+
+class LogFileCleanup extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'LogFileCleanup';
+		this.capabilityName = 'LogFileCleanup';
+	}
+
+	// --- Action: PurgeByAge ---
+
+	get actionPurgeByAge_Description()
+	{
+		return 'Delete log files older than a specified number of days';
+	}
+
+	get actionPurgeByAge_Schema()
+	{
+		return [
+			{ Name: 'Directory', DataType: 'String', Required: true },
+			{ Name: 'Pattern', DataType: 'String', Required: false, Default: '*.log' },
+			{ Name: 'MaxAgeDays', DataType: 'Integer', Required: true },
+			{ Name: 'Recursive', DataType: 'Boolean', Required: false, Default: false },
+			{ Name: 'DryRun', DataType: 'Boolean', Required: false, Default: true }
+		];
+	}
+
+	actionPurgeByAge(pSettings, pWorkItem, fCallback, fReportProgress)
+	{
+		let tmpDir = pSettings.Directory;
+		let tmpPattern = pSettings.Pattern || '*.log';
+		let tmpDays = parseInt(pSettings.MaxAgeDays, 10);
+		let tmpRecursive = pSettings.Recursive ? '' : '-maxdepth 1';
+		let tmpAction = pSettings.DryRun ? '-print' : '-print -delete';
+
+		let tmpCmd = `find ${tmpDir} ${tmpRecursive} -name '${tmpPattern}' -type f -mtime +${tmpDays} ${tmpAction}`;
+
+		fReportProgress({ Percent: 10, Message: `Scanning ${tmpDir} for files older than ${tmpDays} days...` });
+
+		libChildProcess.exec(tmpCmd, { timeout: 120000, maxBuffer: 10 * 1024 * 1024 }, (pError, pStdOut, pStdErr) =>
+		{
+			if (pError && pError.code !== 0)
+			{
+				return fCallback(pError);
+			}
+
+			let tmpFiles = pStdOut.trim().split('\n').filter((pLine) => pLine.length > 0);
+
+			return fCallback(null, {
+				Outputs: {
+					FilesFound: tmpFiles.length,
+					Files: tmpFiles.slice(0, 200),
+					DryRun: !!pSettings.DryRun,
+					Truncated: tmpFiles.length > 200
+				},
+				Log: [
+					pSettings.DryRun
+						? `DRY RUN: Found ${tmpFiles.length} files to delete`
+						: `Deleted ${tmpFiles.length} files`
+				]
+			});
+		});
+	}
+
+	// --- Action: PurgeBySize ---
+
+	get actionPurgeBySize_Description()
+	{
+		return 'Delete log files larger than a specified size';
+	}
+
+	get actionPurgeBySize_Schema()
+	{
+		return [
+			{ Name: 'Directory', DataType: 'String', Required: true },
+			{ Name: 'Pattern', DataType: 'String', Required: false, Default: '*.log' },
+			{ Name: 'MaxSizeMB', DataType: 'Integer', Required: true },
+			{ Name: 'DryRun', DataType: 'Boolean', Required: false, Default: true }
+		];
+	}
+
+	actionPurgeBySize(pSettings, pWorkItem, fCallback)
+	{
+		let tmpDir = pSettings.Directory;
+		let tmpPattern = pSettings.Pattern || '*.log';
+		let tmpSizeMB = parseInt(pSettings.MaxSizeMB, 10);
+		let tmpAction = pSettings.DryRun ? '-print' : '-print -delete';
+
+		let tmpCmd = `find ${tmpDir} -name '${tmpPattern}' -type f -size +${tmpSizeMB}M ${tmpAction}`;
+
+		libChildProcess.exec(tmpCmd, { timeout: 120000, maxBuffer: 10 * 1024 * 1024 }, (pError, pStdOut) =>
+		{
+			if (pError && pError.code !== 0) return fCallback(pError);
+
+			let tmpFiles = pStdOut.trim().split('\n').filter((pLine) => pLine.length > 0);
+
+			return fCallback(null, {
+				Outputs: {
+					FilesFound: tmpFiles.length,
+					Files: tmpFiles.slice(0, 200),
+					DryRun: !!pSettings.DryRun
+				},
+				Log: [
+					pSettings.DryRun
+						? `DRY RUN: Found ${tmpFiles.length} files larger than ${tmpSizeMB}MB`
+						: `Deleted ${tmpFiles.length} files larger than ${tmpSizeMB}MB`
+				]
+			});
+		});
+	}
+
+	// --- Action: ScanUsage ---
+
+	get actionScanUsage_Description()
+	{
+		return 'Report total log directory size and file count by extension';
+	}
+
+	get actionScanUsage_Schema()
+	{
+		return [
+			{ Name: 'Directory', DataType: 'String', Required: true }
+		];
+	}
+
+	actionScanUsage(pSettings, pWorkItem, fCallback)
+	{
+		let tmpDir = pSettings.Directory;
+
+		// Get total size
+		let tmpSizeCmd = `du -sh ${tmpDir} 2>/dev/null | cut -f1`;
+		// Get file count by extension
+		let tmpCountCmd = `find ${tmpDir} -type f | sed 's/.*\\.//' | sort | uniq -c | sort -rn | head -20`;
+
+		libChildProcess.exec(`${tmpSizeCmd} && echo '---SEPARATOR---' && ${tmpCountCmd}`, { timeout: 60000 }, (pError, pStdOut) =>
+		{
+			if (pError) return fCallback(pError);
+
+			let tmpParts = pStdOut.split('---SEPARATOR---');
+			let tmpTotalSize = tmpParts[0].trim();
+			let tmpExtensions = tmpParts[1] ? tmpParts[1].trim().split('\n').map((pLine) =>
+			{
+				let tmpMatch = pLine.trim().match(/(\d+)\s+(.*)/);
+				return tmpMatch ? { Count: parseInt(tmpMatch[1], 10), Extension: tmpMatch[2] } : null;
+			}).filter(Boolean) : [];
+
+			return fCallback(null, {
+				Outputs: { TotalSize: tmpTotalSize, Extensions: tmpExtensions, Directory: tmpDir },
+				Log: [`Log directory ${tmpDir}: ${tmpTotalSize} total`]
+			});
+		});
+	}
+}
+
+// --- Startup ---
+
+let tmpFable = new libFable({ Product: 'LogFileCleanup', ProductVersion: '1.0.0' });
+tmpFable.addServiceType('LogFileCleanup', LogFileCleanup);
+let tmpCap = tmpFable.instantiateServiceProvider('LogFileCleanup');
+
+tmpCap.connect(
+	{
+		ServerURL: process.env.ULTRAVISOR_URL || 'http://localhost:54321',
+		Name: `log-cleanup-${require('os').hostname()}`
+	},
+	(pError) =>
+	{
+		if (pError) throw pError;
+		console.log('Log file cleanup beacon online');
+	});
+
+process.on('SIGTERM', () => { tmpCap.disconnect(() => process.exit(0)); });
+```
+
+## Registered Task Types
+
+- `beacon-logfilecleanup-purgebyage`
+- `beacon-logfilecleanup-purgebysize`
+- `beacon-logfilecleanup-scanusage`
+
+## Key Points
+
+- **DryRun defaults to `true`** -- a safe default that shows what would be deleted without actually deleting
+- **File list is capped** at 200 entries in the output to prevent excessive payload sizes
+- **ScanUsage** provides a quick overview of disk consumption by file type before deciding what to clean
+- Schedule `PurgeByAge` weekly to keep log directories from growing unbounded