@fractary/faber-cli 1.0.0

package/dist/commands/workflow/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Workflow commands - FABER workflow execution
+ *
+ * Provides run, status, resume, pause commands via FaberWorkflow SDK.
+ */
+import { Command } from 'commander';
+/**
+ * Create the run command
+ */
+export declare function createRunCommand(): Command;
+/**
+ * Create the status command
+ */
+export declare function createStatusCommand(): Command;
+/**
+ * Create the resume command
+ */
+export declare function createResumeCommand(): Command;
+/**
+ * Create the pause command
+ */
+export declare function createPauseCommand(): Command;
+/**
+ * Create the recover command
+ */
+export declare function createRecoverCommand(): Command;
+/**
+ * Create the cleanup command
+ */
+export declare function createCleanupCommand(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/workflow/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/workflow/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAkD1C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAiF7C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAyB7C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAoB5C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CA2B9C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CA8B9C"}

package/dist/commands/workflow/index.js

@@ -0,0 +1,298 @@
+/**
+ * Workflow commands - FABER workflow execution
+ *
+ * Provides run, status, resume, pause commands via FaberWorkflow SDK.
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { FaberWorkflow, StateManager } from '@fractary/faber';
+import { parsePositiveInteger } from '../../utils/validation.js';
+/**
+ * Create the run command
+ */
+export function createRunCommand() {
+    return new Command('run')
+        .description('Run FABER workflow')
+        .requiredOption('--work-id <id>', 'Work item ID to process')
+        .option('--autonomy <level>', 'Autonomy level: supervised|assisted|autonomous', 'supervised')
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const workflow = new FaberWorkflow();
+            if (!options.json) {
+                console.log(chalk.blue(`Starting FABER workflow for work item #${options.workId}`));
+                console.log(chalk.gray(`Autonomy: ${options.autonomy}`));
+            }
+            // Add event listener for progress updates
+            workflow.addEventListener((event, data) => {
+                if (options.json)
+                    return;
+                switch (event) {
+                    case 'phase:start':
+                        console.log(chalk.cyan(`\n→ Starting phase: ${String(data.phase || '').toUpperCase()}`));
+                        break;
+                    case 'phase:complete':
+                        console.log(chalk.green(`  ✓ Completed phase: ${data.phase}`));
+                        break;
+                    case 'workflow:fail':
+                    case 'phase:fail':
+                        console.error(chalk.red(`  ✗ Error: ${data.error || 'Unknown error'}`));
+                        break;
+                }
+            });
+            const result = await workflow.run({
+                workId: options.workId,
+                autonomy: options.autonomy,
+            });
+            if (options.json) {
+                console.log(JSON.stringify({ status: 'success', data: result }, null, 2));
+            }
+            else {
+                console.log(chalk.green(`\n✓ Workflow ${result.status}`));
+                console.log(chalk.gray(`  Workflow ID: ${result.workflow_id}`));
+                console.log(chalk.gray(`  Duration: ${result.duration_ms}ms`));
+                console.log(chalk.gray(`  Phases: ${result.phases.map((p) => p.phase).join(' → ')}`));
+            }
+        }
+        catch (error) {
+            handleWorkflowError(error, options);
+        }
+    });
+}
+/**
+ * Create the status command
+ */
+export function createStatusCommand() {
+    return new Command('status')
+        .description('Show workflow status')
+        .option('--work-id <id>', 'Work item ID to check')
+        .option('--workflow-id <id>', 'Workflow ID to check')
+        .option('--verbose', 'Show detailed status')
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const stateManager = new StateManager();
+            if (options.workflowId) {
+                // Status for specific workflow by ID
+                const workflow = new FaberWorkflow();
+                const status = workflow.getStatus(options.workflowId);
+                if (options.json) {
+                    console.log(JSON.stringify({ status: 'success', data: status }, null, 2));
+                }
+                else {
+                    console.log(chalk.bold(`Workflow Status: ${options.workflowId}`));
+                    console.log(`  Current Phase: ${status.currentPhase || 'N/A'}`);
+                    console.log(`  Progress: ${status.progress}%`);
+                }
+            }
+            else if (options.workId) {
+                // Status for work item's active workflow
+                const state = stateManager.getActiveWorkflow(options.workId);
+                if (!state) {
+                    if (options.json) {
+                        console.log(JSON.stringify({
+                            status: 'success',
+                            data: { active: false, message: 'No active workflow' },
+                        }, null, 2));
+                    }
+                    else {
+                        console.log(chalk.yellow(`No active workflow for work item #${options.workId}`));
+                    }
+                    return;
+                }
+                if (options.json) {
+                    console.log(JSON.stringify({ status: 'success', data: state }, null, 2));
+                }
+                else {
+                    console.log(chalk.bold(`Workflow Status: Work Item #${options.workId}`));
+                    console.log(`  Workflow ID: ${state.workflow_id}`);
+                    console.log(`  State: ${getStateColor(state.status)(state.status)}`);
+                    console.log(`  Current Phase: ${state.current_phase || 'N/A'}`);
+                    console.log(`  Started: ${state.started_at || 'N/A'}`);
+                    if (options.verbose && state.phase_states) {
+                        console.log(chalk.yellow('\nPhase Details:'));
+                        Object.entries(state.phase_states).forEach(([phase, phaseState]) => {
+                            const ps = phaseState;
+                            const icon = ps.status === 'completed' ? chalk.green('✓') :
+                                ps.status === 'in_progress' ? chalk.cyan('→') :
+                                    ps.status === 'failed' ? chalk.red('✗') : chalk.gray('○');
+                            console.log(`  ${icon} ${phase}`);
+                        });
+                    }
+                }
+            }
+            else {
+                // List all workflows
+                const workflows = stateManager.listWorkflows();
+                if (options.json) {
+                    console.log(JSON.stringify({ status: 'success', data: workflows }, null, 2));
+                }
+                else {
+                    if (workflows.length === 0) {
+                        console.log(chalk.yellow('No workflows found'));
+                    }
+                    else {
+                        console.log(chalk.bold('Workflows:'));
+                        workflows.forEach((wf) => {
+                            const stateColor = getStateColor(wf.status);
+                            console.log(`  ${wf.workflow_id}: work #${wf.work_id} - ${wf.current_phase || 'N/A'} [${stateColor(wf.status)}]`);
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            handleWorkflowError(error, options);
+        }
+    });
+}
+/**
+ * Create the resume command
+ */
+export function createResumeCommand() {
+    return new Command('resume')
+        .description('Resume a paused workflow')
+        .argument('<workflow_id>', 'Workflow ID to resume')
+        .option('--json', 'Output as JSON')
+        .action(async (workflowId, options) => {
+        try {
+            const workflow = new FaberWorkflow();
+            if (!options.json) {
+                console.log(chalk.blue(`Resuming workflow: ${workflowId}`));
+            }
+            const result = await workflow.resume(workflowId);
+            if (options.json) {
+                console.log(JSON.stringify({ status: 'success', data: result }, null, 2));
+            }
+            else {
+                console.log(chalk.green(`\n✓ Workflow ${result.status}`));
+                console.log(chalk.gray(`  Duration: ${result.duration_ms}ms`));
+            }
+        }
+        catch (error) {
+            handleWorkflowError(error, options);
+        }
+    });
+}
+/**
+ * Create the pause command
+ */
+export function createPauseCommand() {
+    return new Command('pause')
+        .description('Pause a running workflow')
+        .argument('<workflow_id>', 'Workflow ID to pause')
+        .option('--json', 'Output as JSON')
+        .action(async (workflowId, options) => {
+        try {
+            const workflow = new FaberWorkflow();
+            workflow.pause(workflowId);
+            if (options.json) {
+                console.log(JSON.stringify({ status: 'success', data: { paused: workflowId } }, null, 2));
+            }
+            else {
+                console.log(chalk.green(`✓ Paused workflow: ${workflowId}`));
+            }
+        }
+        catch (error) {
+            handleWorkflowError(error, options);
+        }
+    });
+}
+/**
+ * Create the recover command
+ */
+export function createRecoverCommand() {
+    return new Command('recover')
+        .description('Recover a workflow from checkpoint')
+        .argument('<workflow_id>', 'Workflow ID to recover')
+        .option('--checkpoint <id>', 'Specific checkpoint ID to recover from')
+        .option('--phase <phase>', 'Recover to specific phase')
+        .option('--json', 'Output as JSON')
+        .action(async (workflowId, options) => {
+        try {
+            const stateManager = new StateManager();
+            const state = stateManager.recoverWorkflow(workflowId, {
+                checkpointId: options.checkpoint,
+                fromPhase: options.phase,
+            });
+            if (options.json) {
+                console.log(JSON.stringify({ status: 'success', data: state }, null, 2));
+            }
+            else {
+                console.log(chalk.green(`✓ Recovered workflow: ${workflowId}`));
+                console.log(chalk.gray(`  Current phase: ${state.current_phase}`));
+                console.log(chalk.gray(`  Status: ${state.status}`));
+            }
+        }
+        catch (error) {
+            handleWorkflowError(error, options);
+        }
+    });
+}
+/**
+ * Create the cleanup command
+ */
+export function createCleanupCommand() {
+    return new Command('cleanup')
+        .description('Clean up old workflow states')
+        .option('--max-age <days>', 'Delete workflows older than N days', '30')
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        try {
+            const stateManager = new StateManager();
+            const result = stateManager.cleanup(parsePositiveInteger(options.maxAge, 'max age (days)'));
+            if (options.json) {
+                console.log(JSON.stringify({ status: 'success', data: result }, null, 2));
+            }
+            else {
+                if (result.deleted === 0) {
+                    console.log(chalk.yellow('No workflows to clean up'));
+                }
+                else {
+                    console.log(chalk.green(`✓ Cleaned up ${result.deleted} workflow(s)`));
+                }
+                if (result.errors.length > 0) {
+                    console.log(chalk.yellow(`\nErrors (${result.errors.length}):`));
+                    result.errors.forEach((err) => {
+                        console.log(chalk.red(`  - ${err}`));
+                    });
+                }
+            }
+        }
+        catch (error) {
+            handleWorkflowError(error, options);
+        }
+    });
+}
+// Helper functions
+function getStateColor(state) {
+    switch (state) {
+        case 'running':
+            return chalk.cyan;
+        case 'completed':
+            return chalk.green;
+        case 'failed':
+            return chalk.red;
+        case 'paused':
+            return chalk.yellow;
+        case 'idle':
+        case 'pending':
+            return chalk.gray;
+        default:
+            return chalk.white;
+    }
+}
+// Error handling
+function handleWorkflowError(error, options) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (options.json) {
+        console.error(JSON.stringify({
+            status: 'error',
+            error: { code: 'WORKFLOW_ERROR', message },
+        }));
+    }
+    else {
+        console.error(chalk.red('Error:'), message);
+    }
+    process.exit(1);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * FABER CLI - Command-line interface for FABER development toolkit
+ *
+ * Binary: fractary-faber
+ * Entry point for the FABER command-line interface
+ */
+import { Command } from 'commander';
+/**
+ * Create and configure the main CLI program
+ */
+export declare function createFaberCLI(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CA0CxC"}

package/dist/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * FABER CLI - Command-line interface for FABER development toolkit
+ *
+ * Binary: fractary-faber
+ * Entry point for the FABER command-line interface
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { createRunCommand, createStatusCommand, createResumeCommand, createPauseCommand, createRecoverCommand, createCleanupCommand } from './commands/workflow/index.js';
+import { createWorkCommand } from './commands/work/index.js';
+import { createRepoCommand } from './commands/repo/index.js';
+import { createSpecCommand } from './commands/spec/index.js';
+import { createLogsCommand } from './commands/logs/index.js';
+import { createInitCommand } from './commands/init.js';
+const version = '1.0.0';
+/**
+ * Create and configure the main CLI program
+ */
+export function createFaberCLI() {
+    const program = new Command('fractary-faber');
+    program
+        .description('FABER development toolkit (workflow, work, repo, spec, logs)')
+        .version(version)
+        .enablePositionalOptions();
+    // Global options
+    program.option('--debug', 'Enable debug output');
+    // Workflow commands (top-level)
+    program.addCommand(createInitCommand());
+    program.addCommand(createRunCommand());
+    program.addCommand(createStatusCommand());
+    program.addCommand(createResumeCommand());
+    program.addCommand(createPauseCommand());
+    program.addCommand(createRecoverCommand());
+    program.addCommand(createCleanupCommand());
+    // Subcommand trees
+    program.addCommand(createWorkCommand());
+    program.addCommand(createRepoCommand());
+    program.addCommand(createSpecCommand());
+    program.addCommand(createLogsCommand());
+    // Help command
+    program.addCommand(new Command('help')
+        .description('Show help for all commands')
+        .action(() => {
+        program.help();
+    }));
+    // Error handling
+    program.on('error', (error) => {
+        console.error(chalk.red('✖'), error.message);
+        process.exit(1);
+    });
+    return program;
+}
+// Main execution - ESM compatible entry point detection
+const isMainModule = import.meta.url === `file://${process.argv[1]}` ||
+    process.argv[1]?.endsWith('fractary-faber');
+if (isMainModule) {
+    const program = createFaberCLI();
+    program.parse(process.argv);
+    // Show help if no command provided
+    if (!process.argv.slice(2).length) {
+        program.outputHelp();
+        process.exit(0);
+    }
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,14 @@
+export interface ErrorOutput {
+    status: 'error';
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+export declare function formatError(code: string, message: string, details?: unknown): ErrorOutput;
+export declare function printError(message: string, details?: string): void;
+export declare function printSuccess(message: string, details?: string): void;
+export declare function printInfo(message: string, details?: string): void;
+export declare function printWarning(message: string, details?: string): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,OAAO,GAChB,WAAW,CAmBb;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAKlE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAKpE;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAKjE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAKpE"}

package/dist/utils/errors.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+export function formatError(code, message, details) {
+    if (details !== undefined) {
+        return {
+            status: 'error',
+            error: {
+                code,
+                message,
+                details,
+            },
+        };
+    }
+    return {
+        status: 'error',
+        error: {
+            code,
+            message,
+        },
+    };
+}
+export function printError(message, details) {
+    console.error(chalk.red('✖'), message);
+    if (details) {
+        console.error(chalk.gray(details));
+    }
+}
+export function printSuccess(message, details) {
+    console.log(chalk.green('✓'), message);
+    if (details) {
+        console.log(chalk.gray(details));
+    }
+}
+export function printInfo(message, details) {
+    console.log(chalk.blue('ℹ'), message);
+    if (details) {
+        console.log(chalk.gray(details));
+    }
+}
+export function printWarning(message, details) {
+    console.log(chalk.yellow('⚠'), message);
+    if (details) {
+        console.log(chalk.gray(details));
+    }
+}

package/dist/utils/output.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Output formatting utilities for CLI commands
+ */
+export interface JSONOutput<T = unknown> {
+    status: 'success' | 'error';
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export declare function formatJSON<T>(data: T, error?: {
+    code: string;
+    message: string;
+}): JSONOutput<T>;
+export declare function outputJSON<T>(data: JSONOutput<T>): void;
+export declare function formatTable<T extends Record<string, unknown>>(rows: T[]): string;
+//# sourceMappingURL=output.d.ts.map

package/dist/utils/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAY/F;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAEvD;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,MAAM,CA6BhF"}

package/dist/utils/output.js

@@ -0,0 +1,39 @@
+/**
+ * Output formatting utilities for CLI commands
+ */
+export function formatJSON(data, error) {
+    if (error) {
+        return {
+            status: 'error',
+            error,
+        };
+    }
+    return {
+        status: 'success',
+        data,
+    };
+}
+export function outputJSON(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+export function formatTable(rows) {
+    if (rows.length === 0) {
+        return '';
+    }
+    const keys = Object.keys(rows[0]);
+    const columnWidths = keys.map((key) => {
+        const headerWidth = String(key).length;
+        const maxContentWidth = Math.max(...rows.map((row) => String(row[key] ?? '').length));
+        return Math.max(headerWidth, maxContentWidth);
+    });
+    const separator = columnWidths
+        .map((width) => '─'.repeat(width + 2))
+        .join('┼');
+    const header = keys
+        .map((key, i) => ` ${String(key).padEnd(columnWidths[i])} `)
+        .join('┃');
+    const lines = rows.map((row) => keys
+        .map((key, i) => ` ${String(row[key] ?? '').padEnd(columnWidths[i])} `)
+        .join('┃'));
+    return [header, separator, ...lines].join('\n');
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * FABER CLI - Input Validation Utilities
+ *
+ * Common validation functions for CLI inputs
+ */
+/**
+ * Parse and validate an integer string
+ * @param value - String value to parse
+ * @param fieldName - Field name for error messages
+ * @returns Validated integer
+ * @throws Error if value is not a valid integer
+ */
+export declare function parseValidInteger(value: string, fieldName: string): number;
+/**
+ * Parse and validate an optional integer string
+ * @param value - String value to parse (may be undefined)
+ * @param fieldName - Field name for error messages
+ * @returns Validated integer or undefined
+ * @throws Error if value is provided but not a valid integer
+ */
+export declare function parseOptionalInteger(value: string | undefined, fieldName: string): number | undefined;
+/**
+ * Parse and validate a positive integer string
+ * @param value - String value to parse
+ * @param fieldName - Field name for error messages
+ * @returns Validated positive integer
+ * @throws Error if value is not a valid positive integer
+ */
+export declare function parsePositiveInteger(value: string, fieldName: string): number;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAY1E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMrG;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ7E"}

package/dist/utils/validation.js

@@ -0,0 +1,49 @@
+/**
+ * FABER CLI - Input Validation Utilities
+ *
+ * Common validation functions for CLI inputs
+ */
+/**
+ * Parse and validate an integer string
+ * @param value - String value to parse
+ * @param fieldName - Field name for error messages
+ * @returns Validated integer
+ * @throws Error if value is not a valid integer
+ */
+export function parseValidInteger(value, fieldName) {
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        throw new Error(`Invalid ${fieldName}: "${value}" is not a valid integer`);
+    }
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Invalid ${fieldName}: value is not finite`);
+    }
+    return parsed;
+}
+/**
+ * Parse and validate an optional integer string
+ * @param value - String value to parse (may be undefined)
+ * @param fieldName - Field name for error messages
+ * @returns Validated integer or undefined
+ * @throws Error if value is provided but not a valid integer
+ */
+export function parseOptionalInteger(value, fieldName) {
+    if (!value) {
+        return undefined;
+    }
+    return parseValidInteger(value, fieldName);
+}
+/**
+ * Parse and validate a positive integer string
+ * @param value - String value to parse
+ * @param fieldName - Field name for error messages
+ * @returns Validated positive integer
+ * @throws Error if value is not a valid positive integer
+ */
+export function parsePositiveInteger(value, fieldName) {
+    const parsed = parseValidInteger(value, fieldName);
+    if (parsed <= 0) {
+        throw new Error(`Invalid ${fieldName}: must be a positive integer (got ${parsed})`);
+    }
+    return parsed;
+}