anz-legislation 1.2.1

package/dist/commands/get.js

@@ -0,0 +1,99 @@
+/**
+ * Get command - Retrieve legislation by ID
+ */
+import { Command } from 'commander';
+import ora from 'ora';
+import { printWorkDetail, printVersionsTable, printJson, versionsToCsv } from '@output';
+import { logger } from '@utils/logger';
+import { validateWorkId, sanitizeInput } from '@utils/validation';
+import { getGlobalRegistry } from '../providers/index.js';
+import { toLegacyVersions, toLegacyWork } from '../providers/output-adapters.js';
+export const getCommand = new Command()
+    .name('get')
+    .description('Get legislation by ID')
+    .argument('<id>', 'Work ID (e.g., act_public_1989_18)')
+    .option('--versions', 'Show version history')
+    .option('--format <format>', 'Output format (table, json, csv)', 'table')
+    .action(async (workId, options, command) => {
+    const globalOptions = command.parent ? command.parent.opts() : {};
+    const jurisdiction = globalOptions.jurisdiction || 'nz';
+    const spinner = ora(`Retrieving ${jurisdiction} legislation...`).start();
+    try {
+        // Get provider
+        const registry = getGlobalRegistry();
+        const provider = registry.get(jurisdiction);
+        if (!provider) {
+            spinner.stop();
+            console.error(`❌ Error: Unknown jurisdiction "${jurisdiction}"`);
+            process.exit(1);
+        }
+        // Sanitize and validate work ID
+        const sanitizedWorkId = sanitizeInput(workId);
+        // NZ-specific ID validation only if jurisdiction is nz
+        if (jurisdiction === 'nz') {
+            const validation = validateWorkId(sanitizedWorkId);
+            if (!validation.valid) {
+                spinner.stop();
+                logger.error('Work ID validation failed', undefined, {
+                    workId,
+                    errors: validation.errors,
+                });
+                console.error('❌ Invalid work ID format:');
+                validation.errors?.forEach(err => {
+                    console.error(`  - ${err.message}`);
+                });
+                console.error('\nExpected format: API work ID (e.g., act_public_1989_18)');
+                process.exit(3);
+            }
+        }
+        if (options.versions) {
+            // Get version history
+            const versions = await provider.getVersions(sanitizedWorkId);
+            const work = await provider.getWork(sanitizedWorkId);
+            const legacyVersions = toLegacyVersions(versions, work.type);
+            spinner.stop();
+            switch (options.format.toLowerCase()) {
+                case 'json':
+                    printJson(versions);
+                    break;
+                case 'csv':
+                    console.log(versionsToCsv(legacyVersions));
+                    break;
+                case 'table':
+                default:
+                    printVersionsTable(legacyVersions);
+                    break;
+            }
+        }
+        else {
+            // Get work details
+            const work = await provider.getWork(sanitizedWorkId);
+            const legacyWork = toLegacyWork(work);
+            spinner.stop();
+            switch (options.format.toLowerCase()) {
+                case 'json':
+                    printJson(work);
+                    break;
+                case 'csv':
+                    console.log('Note: CSV format not ideal for single work. Use table or json.');
+                    printWorkDetail(legacyWork);
+                    break;
+                case 'table':
+                default:
+                    printWorkDetail(legacyWork);
+                    break;
+            }
+        }
+    }
+    catch (error) {
+        spinner.stop();
+        logger.error('Failed to retrieve legislation', error instanceof Error ? error : undefined, {
+            workId,
+        });
+        if (error instanceof Error) {
+            console.error(`❌ Error: ${error.message}`);
+            process.exit(1);
+        }
+        throw error;
+    }
+});

package/dist/commands/help.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Interactive Help Command
+ * Provides menu-driven help navigation for ANZ Legislation CLI
+ */
+import { Command } from 'commander';
+/**
+ * Create interactive help command
+ */
+export declare function createInteractiveHelpCommand(): Command;
+/**
+ * Create contextual help command
+ */
+export declare function createContextualHelpCommand(): Command;

package/dist/commands/help.js

@@ -0,0 +1,298 @@
+/**
+ * Interactive Help Command
+ * Provides menu-driven help navigation for ANZ Legislation CLI
+ */
+import * as readline from 'readline';
+import chalk from 'chalk';
+import { Command } from 'commander';
+const helpTopics = [
+    {
+        id: 'search',
+        title: 'Search Legislation',
+        description: 'Search for legislation works by keyword, type, or status',
+        examples: [
+            'nzlegislation search --query "health"',
+            'nzlegislation search --query "health" --type act --limit 10',
+            'nzlegislation search --query "covid" --status in-force',
+        ],
+        relatedCommands: ['get', 'export'],
+    },
+    {
+        id: 'get',
+        title: 'Get Legislation Details',
+        description: 'Retrieve detailed information about a specific work',
+        examples: [
+            'nzlegislation get "act_public_1989_18"',
+            'nzlegislation get "act_public_1989_18" --versions',
+            'nzlegislation get "act_public_1989_18" --format json',
+        ],
+        relatedCommands: ['search', 'cite'],
+    },
+    {
+        id: 'export',
+        title: 'Export Legislation',
+        description: 'Export search results to CSV, JSON, or NDJSON format',
+        examples: [
+            'nzlegislation export --query "health" --output health.csv',
+            'nzlegislation export --query "health" --output health.json --format json',
+            'nzlegislation export --query "health" --output health.ndjson --format ndjson',
+        ],
+        relatedCommands: ['search'],
+    },
+    {
+        id: 'cite',
+        title: 'Generate Citations',
+        description: 'Generate citations in various academic styles',
+        examples: [
+            'nzlegislation cite "act_public_1989_18" --style nzmj',
+            'nzlegislation cite "act_public_1989_18" --style bibtex',
+            'nzlegislation cite "act_public_1989_18" --style ris',
+            'nzlegislation cite "act_public_1989_18" --style enw',
+            'nzlegislation cite "act_public_1989_18" --style apa',
+        ],
+        relatedCommands: ['get'],
+    },
+    {
+        id: 'config',
+        title: 'Configuration',
+        description: 'Manage API key and CLI settings',
+        examples: [
+            'nzlegislation config --key YOUR_API_KEY',
+            'nzlegislation config --show',
+            'nzlegislation config --clear',
+        ],
+        relatedCommands: [],
+    },
+    {
+        id: 'cache',
+        title: 'Cache Management',
+        description: 'View and manage API response cache',
+        examples: [
+            'nzlegislation cache --status',
+            'nzlegislation cache --clear',
+            'nzlegislation cache --stats',
+        ],
+        relatedCommands: [],
+    },
+    {
+        id: 'troubleshooting',
+        title: 'Troubleshooting',
+        description: 'Common issues and solutions',
+        examples: [
+            chalk.yellow('Issue: API key not working'),
+            '  → Run: nzlegislation config --show',
+            '  → Run: nzlegislation config --key YOUR_API_KEY',
+            '',
+            chalk.yellow('Issue: Rate limit exceeded'),
+            '  → Wait 5 minutes and try again',
+            '  → Use --limit to reduce requests',
+            '',
+            chalk.yellow('Issue: Network error'),
+            '  → Check internet connection',
+            '  → Verify API URL: https://api.legislation.govt.nz',
+        ],
+        relatedCommands: ['config'],
+    },
+];
+/**
+ * Create interactive help command
+ */
+export function createInteractiveHelpCommand() {
+    const cmd = new Command();
+    cmd
+        .name('help-interactive')
+        .alias('help-i')
+        .description('Interactive help system with menu navigation')
+        .action(async () => {
+        console.log(chalk.blue.bold('\n📚 ANZ Legislation - Interactive Help\n'));
+        console.log('Use arrow keys to navigate, Enter to select, q to quit\n');
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        let selectedIndex = 0;
+        const showMenu = () => {
+            console.clear();
+            console.log(chalk.blue.bold('\n📚 ANZ Legislation - Interactive Help\n'));
+            console.log('Select a topic:\n');
+            helpTopics.forEach((topic, index) => {
+                const isSelected = index === selectedIndex;
+                const symbol = isSelected ? chalk.green('❯') : ' ';
+                const color = isSelected ? chalk.green.bold : chalk.white;
+                console.log(`${symbol} ${color(topic.title)} - ${topic.description}`);
+            });
+            console.log('\n' + chalk.gray('q - Quit'));
+            console.log(chalk.gray('↑/↓ - Navigate | Enter - Select\n'));
+        };
+        const showTopic = (topic) => {
+            console.clear();
+            console.log(chalk.blue.bold(`\n📖 ${topic.title}\n`));
+            console.log(`${topic.description}\n`);
+            console.log(chalk.yellow.bold('Examples:'));
+            topic.examples.forEach(example => {
+                console.log(`  ${chalk.cyan(example)}`);
+            });
+            if (topic.relatedCommands && topic.relatedCommands.length > 0) {
+                console.log('\n' + chalk.yellow.bold('Related Commands:'));
+                topic.relatedCommands.forEach(cmdName => {
+                    console.log(`  ${chalk.green(`nzlegislation ${cmdName} --help`)}`);
+                });
+            }
+            console.log('\n' + chalk.gray('Press Enter to return to menu...'));
+        };
+        // Handle keyboard input
+        const handleInput = async () => {
+            return new Promise(resolve => {
+                rl.once('data', (key) => {
+                    const input = key.toString().toLowerCase();
+                    if (input === 'q') {
+                        console.log(chalk.green('\n👋 Goodbye!\n'));
+                        rl.close();
+                        process.exit(0);
+                    }
+                    if (input === '\r' || input === '\n') {
+                        // Show selected topic
+                        const topic = helpTopics[selectedIndex];
+                        showTopic(topic);
+                        // Wait for Enter to return
+                        rl.once('data', () => {
+                            showMenu();
+                            void handleInput().then(resolve);
+                        });
+                        return;
+                    }
+                    if (input === '\x1b[A') {
+                        // Up arrow
+                        selectedIndex = Math.max(0, selectedIndex - 1);
+                    }
+                    else if (input === '\x1b[B') {
+                        // Down arrow
+                        selectedIndex = Math.min(helpTopics.length - 1, selectedIndex + 1);
+                    }
+                    showMenu();
+                    void handleInput().then(resolve);
+                });
+            });
+        };
+        showMenu();
+        await handleInput();
+    });
+    return cmd;
+}
+/**
+ * Create contextual help command
+ */
+export function createContextualHelpCommand() {
+    const cmd = new Command();
+    cmd
+        .name('help-context')
+        .description('Show contextual help for common scenarios')
+        .argument('[scenario]', 'Scenario: auth, rate-limit, network, export, cite')
+        .action((scenario) => {
+        if (!scenario) {
+            console.log(chalk.blue.bold('\n📚 Contextual Help\n'));
+            console.log('Available scenarios:\n');
+            console.log('  auth       - Authentication and API key issues');
+            console.log('  rate-limit - Rate limiting and quotas');
+            console.log('  network    - Network and connectivity issues');
+            console.log('  export     - Export format and file issues');
+            console.log('  cite       - Citation format and style issues');
+            console.log('\nUsage: nzlegislation help-context <scenario>\n');
+            return;
+        }
+        const scenarios = {
+            auth: [
+                chalk.yellow.bold('Authentication Issues'),
+                '',
+                chalk.green('Check API Key Configuration:'),
+                '  nzlegislation config --show',
+                '',
+                chalk.green('Set API Key:'),
+                '  nzlegislation config --key YOUR_API_KEY',
+                '',
+                chalk.green('Get API Key:'),
+                '  Visit: https://api.legislation.govt.nz/docs/',
+                '',
+                chalk.green('Environment Variable:'),
+                '  export NZ_LEGISLATION_API_KEY=your_key',
+            ],
+            'rate-limit': [
+                chalk.yellow.bold('Rate Limiting'),
+                '',
+                chalk.green('Current Limits:'),
+                '  • 10,000 requests/day',
+                '  • 2,000 requests/5min (burst)',
+                '',
+                chalk.green('Solutions:'),
+                '  1. Wait 5 minutes and retry',
+                '  2. Use --limit to reduce batch size',
+                '  3. Enable caching: nzlegislation cache --status',
+                '  4. Export large datasets in chunks',
+                '',
+                chalk.green('Example:'),
+                '  nzlegislation search --query "health" --limit 50',
+            ],
+            network: [
+                chalk.yellow.bold('Network Issues'),
+                '',
+                chalk.green('Check Connection:'),
+                '  • Verify internet connection',
+                '  • Check API status: https://api.legislation.govt.nz',
+                '  • Try: curl https://api.legislation.govt.nz',
+                '',
+                chalk.green('Firewall/Proxy:'),
+                '  • Ensure HTTPS (port 443) is allowed',
+                '  • Configure proxy if needed',
+                '',
+                chalk.green('Timeout Issues:'),
+                '  • Increase timeout: export NZ_LEGISLATION_TIMEOUT=60000',
+            ],
+            export: [
+                chalk.yellow.bold('Export Issues'),
+                '',
+                chalk.green('Supported Formats:'),
+                '  • table (default) - Pretty terminal table',
+                '  • json - JSON format',
+                '  • csv - CSV format',
+                '  • ndjson - Newline-delimited JSON',
+                '',
+                chalk.green('Examples:'),
+                '  nzlegislation export --query "health" --output health.csv',
+                '  nzlegislation export --query "health" --format json',
+                '',
+                chalk.green('Troubleshooting:'),
+                '  • Check file path permissions',
+                '  • Ensure directory exists',
+                '  • Use absolute paths if needed',
+            ],
+            cite: [
+                chalk.yellow.bold('Citation Issues'),
+                '',
+                chalk.green('Supported Styles:'),
+                '  • nzmj - New Zealand Medical Journal',
+                '  • bibtex - BibTeX format',
+                '  • ris - RIS format (EndNote, Mendeley)',
+                '  • enw - EndNote import format',
+                '  • apa - APA style',
+                '',
+                chalk.green('Examples:'),
+                '  nzlegislation cite "act_public_1989_18" --style nzmj',
+                '  nzlegislation cite "act_public_1989_18" --style bibtex',
+                '  nzlegislation cite "act_public_1989_18" --style enw',
+                '',
+                chalk.green('Missing Data:'),
+                '  • Some works may lack metadata',
+                '  • Use --verbose to see available fields',
+            ],
+        };
+        const help = scenarios[scenario];
+        if (!help) {
+            console.log(chalk.red(`\nUnknown scenario: ${scenario}\n`));
+            console.log('Run without arguments to see available scenarios.\n');
+            process.exit(1);
+        }
+        console.log(help.join('\n'));
+        console.log();
+    });
+    return cmd;
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Search command - Search for legislation
+ */
+import { Command } from 'commander';
+export declare const searchCommand: Command;

package/dist/commands/search.js

@@ -0,0 +1,96 @@
+/**
+ * Search command - Search for legislation
+ */
+import { Command } from 'commander';
+import ora from 'ora';
+import { printTable, printJson, worksToCsv } from '@output';
+import { logger } from '@utils/logger';
+import { validateSearchParams, sanitizeInput } from '@utils/validation';
+import { getGlobalRegistry } from '../providers/index.js';
+import { toLegacySearchResults } from '../providers/output-adapters.js';
+export const searchCommand = new Command()
+    .name('search')
+    .description('Search for legislation')
+    .requiredOption('-q, --query <text>', 'Search query')
+    .option('-t, --type <type>', 'Filter by type (act, bill, regulation, instrument)')
+    .option('-s, --status <status>', 'Filter by status (in-force, repealed, etc.)')
+    .option('--from <date>', 'Filter from date (YYYY-MM-DD)')
+    .option('--to <date>', 'Filter to date (YYYY-MM-DD)')
+    .option('-l, --limit <number>', 'Maximum results (default: 25, max: 100)', '25')
+    .option('-o, --offset <number>', 'Result offset for pagination', '0')
+    .option('--format <format>', 'Output format (table, json, csv)', 'table')
+    .action(async (options, command) => {
+    const globalOptions = command.parent ? command.parent.opts() : {};
+    const jurisdiction = globalOptions.jurisdiction || 'nz';
+    const spinner = ora(`Searching ${jurisdiction} legislation...`).start();
+    try {
+        // Get provider
+        const registry = getGlobalRegistry();
+        const provider = registry.get(jurisdiction);
+        if (!provider) {
+            spinner.stop();
+            console.error(`❌ Error: Unknown jurisdiction "${jurisdiction}"`);
+            process.exit(1);
+        }
+        // Sanitize inputs
+        const sanitizedOptions = {
+            ...options,
+            query: sanitizeInput(options.query),
+            type: options.type ? sanitizeInput(options.type) : undefined,
+            status: options.status ? sanitizeInput(options.status) : undefined,
+            from: options.from ? sanitizeInput(options.from) : undefined,
+            to: options.to ? sanitizeInput(options.to) : undefined,
+        };
+        // Validate parameters
+        const validation = validateSearchParams(sanitizedOptions);
+        if (!validation.valid) {
+            spinner.stop();
+            logger.error('Validation failed', undefined, { errors: validation.errors });
+            console.error('❌ Validation errors:');
+            validation.errors?.forEach(err => {
+                console.error(`  - ${err.field}: ${err.message}`);
+            });
+            process.exit(3);
+        }
+        const validatedParams = validation.data;
+        const normalizedStatus = validatedParams.status === 'not-yet-in-force'
+            ? 'not-in-force'
+            : validatedParams.status === 'in-force' || validatedParams.status === 'repealed'
+                ? validatedParams.status
+                : undefined;
+        // Map Command-style WorkType to SearchParams WorkType
+        const searchParams = {
+            query: validatedParams.query,
+            type: validatedParams.type,
+            status: normalizedStatus,
+            from: validatedParams.from,
+            to: validatedParams.to,
+            limit: validatedParams.limit,
+            offset: validatedParams.offset,
+        };
+        const results = await provider.search(searchParams);
+        const legacyResults = toLegacySearchResults(results);
+        spinner.stop();
+        switch (validatedParams.format.toLowerCase()) {
+            case 'json':
+                printJson(results);
+                break;
+            case 'csv':
+                console.log(worksToCsv(legacyResults));
+                break;
+            case 'table':
+            default:
+                printTable(legacyResults);
+                break;
+        }
+    }
+    catch (error) {
+        spinner.stop();
+        logger.error('Search failed', error instanceof Error ? error : undefined, { options });
+        if (error instanceof Error) {
+            console.error(`❌ Error: ${error.message}`);
+            process.exit(1);
+        }
+        throw error;
+    }
+});

package/dist/commands/stream.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Stream Command - Stream large exports with minimal memory usage
+ */
+import { Command } from 'commander';
+export declare const streamCommand: Command;

package/dist/commands/stream.js

@@ -0,0 +1,100 @@
+/**
+ * Stream Command - Stream large exports with minimal memory usage
+ */
+import { Command } from 'commander';
+import ora from 'ora';
+import { StreamExporter } from '@utils/streaming';
+export const streamCommand = new Command()
+    .name('stream')
+    .description('Stream large exports with minimal memory usage')
+    .requiredOption('-q, --query <text>', 'Search query')
+    .requiredOption('-o, --output <file>', 'Output file path')
+    .option('-t, --type <type>', 'Filter by type (act, bill, regulation, instrument)')
+    .option('-s, --status <status>', 'Filter by status')
+    .option('--from <date>', 'Filter from date (YYYY-MM-DD)')
+    .option('--to <date>', 'Filter to date (YYYY-MM-DD)')
+    .option('-l, --limit <number>', 'Maximum results (default: unlimited)')
+    .option('-f, --format <format>', 'Output format (csv, json, ndjson)', 'csv')
+    .option('-b, --batch-size <number>', 'Results per batch', '100')
+    .option('-c, --concurrency <number>', 'API concurrency', '3')
+    .option('--no-metadata', 'Exclude metadata from output')
+    .action(async (options) => {
+    const spinner = ora('Starting stream export...').start();
+    try {
+        // Validate format
+        if (!['csv', 'json', 'ndjson'].includes(options.format)) {
+            throw new Error('Format must be csv, json, or ndjson');
+        }
+        // Parse options
+        const exportOptions = {
+            query: options.query,
+            outputPath: options.output,
+            format: options.format,
+            includeMetadata: !options.noMetadata,
+            batchSize: parseInt(options.batchSize, 10),
+            maxResults: options.limit ? parseInt(options.limit, 10) : undefined,
+            concurrency: parseInt(options.concurrency, 10),
+        };
+        // Create exporter
+        const exporter = new StreamExporter(exportOptions);
+        // Prepare search parameters
+        const searchParams = {
+            query: options.query,
+            type: options.type,
+            status: options.status,
+            from: options.from,
+            to: options.to,
+        };
+        spinner.succeed('Starting stream export');
+        console.log('\nExport Configuration:');
+        console.log('─'.repeat(50));
+        console.log(`  Query:      ${options.query}`);
+        console.log(`  Output:     ${options.output}`);
+        console.log(`  Format:     ${options.format.toUpperCase()}`);
+        console.log(`  Batch Size: ${exportOptions.batchSize}`);
+        console.log(`  Concurrency: ${exportOptions.concurrency}`);
+        console.log(`  Max Results: ${exportOptions.maxResults || 'unlimited'}`);
+        console.log(`  Metadata:   ${exportOptions.includeMetadata ? 'Included' : 'Excluded'}`);
+        console.log('\nStreaming... (Press Ctrl+C to cancel)\n');
+        // Track progress
+        let lastPercent = 0;
+        const startTime = Date.now();
+        const result = await exporter.export(searchParams, progress => {
+            // Only show progress every 10%
+            if (progress.percent - lastPercent >= 10) {
+                const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+                const eta = progress.estimatedTimeRemaining
+                    ? `${(progress.estimatedTimeRemaining / 1000).toFixed(0)}s`
+                    : 'Calculating...';
+                console.log(`  ${progress.percent}% | ${progress.processed} items | ${elapsed}s elapsed | ETA: ${eta}`);
+                lastPercent = progress.percent;
+            }
+        });
+        const totalTime = ((Date.now() - startTime) / 1000).toFixed(1);
+        spinner.succeed('Stream export complete');
+        console.log('\nExport Summary:');
+        console.log('─'.repeat(50));
+        console.log(`  Items Exported: ${result.processed}`);
+        console.log(`  File Size:      ${(result.bytesWritten / 1024).toFixed(2)} KB`);
+        console.log(`  Total Time:     ${totalTime}s`);
+        console.log(`  Output File:    ${options.output}`);
+        console.log(`  Format:         ${options.format.toUpperCase()}`);
+        // Performance stats
+        const itemsPerSecond = ((result.processed / (Date.now() - startTime)) * 1000).toFixed(2);
+        console.log(`  Throughput:     ${itemsPerSecond} items/sec`);
+        // Memory usage
+        const memoryUsage = process.memoryUsage();
+        console.log(`  Memory Used:    ${(memoryUsage.heapUsed / 1024 / 1024).toFixed(2)} MB`);
+    }
+    catch (error) {
+        spinner.fail('Stream export failed');
+        console.error('\nError: Stream export failed.');
+        if (error instanceof Error && error.message.includes('EACCES')) {
+            console.log('\nHint: Check file permissions and ensure the output directory exists.');
+        }
+        else if (error instanceof Error && error.message.includes('ENOSPC')) {
+            console.log('\nHint: Disk space is full. Free up space and try again.');
+        }
+        process.exit(1);
+    }
+});