sequant 1.0.0

package/dist/src/lib/workflow/cli-args.js

@@ -0,0 +1,210 @@
+/**
+ * CLI Argument Parser for Pipeline Scripts
+ *
+ * Typed argument parsing with support for common flags used across all scripts.
+ *
+ * @example
+ * ```typescript
+ * import { parseArgs } from './lib/cli-args'
+ *
+ * const args = parseArgs(process.argv.slice(2))
+ * console.log(args.city)    // 'nashville'
+ * console.log(args.limit)   // 10
+ * console.log(args.dryRun)  // true
+ * ```
+ */
+/**
+ * Parse command line arguments into a typed object.
+ *
+ * Supports two flag formats:
+ * - `--flag=value` (equals format)
+ * - `--flag value` (space-separated format)
+ *
+ * Boolean flags:
+ * - `--dry-run` or `--dryRun` → dryRun: true
+ * - `--verbose` or `-v` → verbose: true
+ * - `--yes` or `-y` → yes: true
+ *
+ * @param argv - Command line arguments (typically `process.argv.slice(2)`)
+ * @param defaults - Optional default values
+ * @returns Parsed arguments object
+ *
+ * @example
+ * ```typescript
+ * // With default city
+ * const args = parseArgs(['--limit', '5'], { city: 'nashville' })
+ * // args.city === 'nashville'
+ * // args.limit === 5
+ *
+ * // Boolean flags
+ * const args2 = parseArgs(['--dry-run', '--verbose'])
+ * // args2.dryRun === true
+ * // args2.verbose === true
+ * ```
+ */
+export function parseArgs(argv, defaults) {
+    const result = {
+        city: defaults?.city,
+        limit: defaults?.limit,
+        dryRun: defaults?.dryRun ?? false,
+        verbose: defaults?.verbose ?? false,
+        yes: defaults?.yes ?? false,
+        positional: [],
+    };
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        // Boolean flags (no value)
+        if (arg === '--dry-run' || arg === '--dryRun') {
+            result.dryRun = true;
+            i++;
+            continue;
+        }
+        if (arg === '--verbose' || arg === '-v') {
+            result.verbose = true;
+            i++;
+            continue;
+        }
+        if (arg === '--yes' || arg === '-y') {
+            result.yes = true;
+            i++;
+            continue;
+        }
+        // Handle --flag=value format
+        if (arg.startsWith('--') && arg.includes('=')) {
+            const equalsIndex = arg.indexOf('=');
+            const key = arg.slice(2, equalsIndex);
+            const value = arg.slice(equalsIndex + 1);
+            const normalizedKey = normalizeKey(key);
+            result[normalizedKey] = parseValue(normalizedKey, value);
+            i++;
+            continue;
+        }
+        // Handle --flag value format
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const normalizedKey = normalizeKey(key);
+            const nextArg = argv[i + 1];
+            // Check if next argument exists and is not another flag
+            if (nextArg !== undefined && !nextArg.startsWith('-')) {
+                result[normalizedKey] = parseValue(normalizedKey, nextArg);
+                i += 2;
+            }
+            else {
+                // Treat as boolean flag
+                result[normalizedKey] = true;
+                i++;
+            }
+            continue;
+        }
+        // Handle short flags like -v, -y (already handled above)
+        if (arg.startsWith('-') && arg.length === 2) {
+            i++;
+            continue;
+        }
+        // Positional argument
+        result.positional.push(arg);
+        i++;
+    }
+    return result;
+}
+/**
+ * Normalize a flag key to camelCase.
+ * Converts kebab-case to camelCase (e.g., 'dry-run' → 'dryRun').
+ *
+ * @param key - The flag key to normalize
+ * @returns Normalized key in camelCase
+ */
+export function normalizeKey(key) {
+    return key.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/**
+ * Parse a value based on expected type for known keys.
+ * Numbers are parsed for 'limit', 'count', 'max', 'min', 'timeout'.
+ *
+ * @param key - The normalized key
+ * @param value - The string value
+ * @returns Parsed value (number or string)
+ */
+export function parseValue(key, value) {
+    const numericKeys = ['limit', 'count', 'max', 'min', 'timeout', 'since', 'days'];
+    if (numericKeys.includes(key)) {
+        const parsed = parseInt(value, 10);
+        return isNaN(parsed) ? value : parsed;
+    }
+    return value;
+}
+/**
+ * Get a required string argument, throwing an error if missing.
+ *
+ * @param args - Parsed arguments
+ * @param key - Argument key to get
+ * @param errorMessage - Custom error message if missing
+ * @returns The argument value
+ * @throws Error if argument is missing
+ *
+ * @example
+ * ```typescript
+ * const city = getRequiredArg(args, 'city', 'Missing required --city argument')
+ * ```
+ */
+export function getRequiredArg(args, key, errorMessage) {
+    const value = args[key];
+    if (value === undefined || value === '') {
+        throw new Error(errorMessage ?? `Missing required argument: --${key}`);
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`Argument --${key} must be a string`);
+    }
+    return value;
+}
+/**
+ * Check if help was requested via --help or -h flag.
+ *
+ * @param argv - Command line arguments
+ * @returns True if help was requested
+ */
+export function isHelpRequested(argv) {
+    return argv.includes('--help') || argv.includes('-h');
+}
+/**
+ * Print usage information for a script.
+ *
+ * @param scriptName - Name of the script
+ * @param description - Brief description
+ * @param options - Available options with descriptions
+ * @param examples - Usage examples
+ *
+ * @example
+ * ```typescript
+ * if (isHelpRequested(process.argv)) {
+ *   printUsage('discover-shops', 'Discover matcha shops for a city', {
+ *     '--city <slug>': 'City slug (required)',
+ *     '--limit <n>': 'Limit API calls',
+ *     '--dry-run': 'Preview mode, no database writes',
+ *   }, [
+ *     'npx tsx scripts/discover-shops.ts --city nashville',
+ *     'npx tsx scripts/discover-shops.ts --city nashville --limit 5',
+ *   ])
+ *   process.exit(0)
+ * }
+ * ```
+ */
+export function printUsage(scriptName, description, options, examples) {
+    console.log(`\n${scriptName}`);
+    console.log(`${'─'.repeat(scriptName.length)}\n`);
+    console.log(description);
+    console.log('\nOptions:');
+    const maxKeyLen = Math.max(...Object.keys(options).map(k => k.length));
+    for (const [key, desc] of Object.entries(options)) {
+        console.log(`  ${key.padEnd(maxKeyLen + 2)} ${desc}`);
+    }
+    if (examples && examples.length > 0) {
+        console.log('\nExamples:');
+        for (const example of examples) {
+            console.log(`  ${example}`);
+        }
+    }
+    console.log('');
+}
+//# sourceMappingURL=cli-args.js.map

package/dist/src/lib/workflow/cli-args.js.map

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

package/dist/src/lib/workflow/execute-issues.d.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env npx tsx
+/**
+ * execute-issues.ts - TypeScript Claude Code Workflow Automation
+ *
+ * Executes /spec → /exec → /test → /qa workflow for GitHub issues.
+ * TypeScript port of scripts/execute-issues.sh with added features.
+ *
+ * Usage:
+ *   npx tsx --env-file=.env.local scripts/dev/execute-issues.ts 123        # Single issue
+ *   npx tsx --env-file=.env.local scripts/dev/execute-issues.ts 123 124 125 # Multiple parallel
+ *   PHASES=exec,qa npx tsx --env-file=.env.local scripts/dev/execute-issues.ts 123  # Custom phases
+ *   PHASES=spec,testgen,exec,qa npx tsx --env-file=.env.local scripts/dev/execute-issues.ts 123  # With test generation
+ *   npx tsx --env-file=.env.local scripts/dev/execute-issues.ts --batch "123 124" --batch "125 126"
+ *   npx tsx --env-file=.env.local scripts/dev/execute-issues.ts --sequential 123 124 125  # Respect dependencies
+ *   QUALITY_LOOP=true npx tsx --env-file=.env.local scripts/dev/execute-issues.ts 123     # Auto-iterate
+ *   npx tsx scripts/dev/execute-issues.ts --test            # Run quick validation tests
+ *   npx tsx scripts/dev/execute-issues.ts --cleanup-orphans # Clean stale runs
+ *
+ * Important:
+ *   Use --env-file=.env.local to enable database logging to workflow_runs table.
+ *   Without this flag, workflow runs will not be recorded (warning shown at startup).
+ *
+ * Environment Variables:
+ *   PHASES           - Comma-separated phases (default: spec,exec,qa)
+ *                      Available: spec, testgen, exec, test, qa, loop
+ *                      Note: testgen requires /spec to have run first with verification criteria
+ *   PHASE_TIMEOUT    - Timeout in seconds per phase (default: 1800)
+ *   QUALITY_LOOP     - Enable auto-iteration (default: false). Auto-includes testgen phase.
+ *   MAX_ITERATIONS   - Max fix iterations per phase (default: 3)
+ *   SKIP_VERIFICATION - Skip /exec verification (default: false)
+ *
+ * Features:
+ *   - Auto-detect UI issues for /test inclusion
+ *   - Optional /testgen phase for shift-left testing (requires /spec comment)
+ *   - Dependency detection and sequential execution (#355)
+ *   - Quality loop mode with /loop iterations
+ *   - Post-exec verification to catch hallucinated implementations
+ *   - Structured logging to workflow_runs table
+ *   - Crash cleanup for orphaned runs
+ */
+export {};
+//# sourceMappingURL=execute-issues.d.ts.map

package/dist/src/lib/workflow/execute-issues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-issues.d.ts","sourceRoot":"","sources":["../../../../src/lib/workflow/execute-issues.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG"}