feat: migrate bash cron utilities to TypeScript

[jonit-dev]

Summary

This PR implements Phases 1-6 of the PRD to migrate bash business logic from scripts/night-watch-helpers.sh to TypeScript modules. This makes the code testable with vitest and provides a cleaner CLI interface for cron scripts.

Changes

New Modules (packages/core/src/utils/)

• git-utils.ts: getBranchTipTimestamp, detectDefaultBranch, resolveWorktreeBaseRef
• worktree-manager.ts: prepareBranchWorktree, prepareDetachedWorktree, cleanupWorktrees
• claim-manager.ts: claimPrd, releaseClaim, isClaimed, readClaimInfo
• log-utils.ts: rotateLog, checkRateLimited
• prd-discovery.ts: findEligiblePrd, findEligibleBoardIssue, sortPrdsByPriority

Extended Modules

• status-data.ts: Added acquireLock, releaseLock functions
• prd-utils.ts: Added markPrdDone function

CLI Command

• cron.ts: New night-watch cron command group with subcommands:
  • detect-branch - Detect default branch
  • acquire-lock / release-lock - Lock file management
  • find-eligible - Find eligible PRD for execution
  • claim / release-claim / is-claimed - PRD claim management
  • mark-done - Mark PRD as done
  • prepare-worktree / cleanup-worktrees - Worktree management
  • check-rate-limit / rotate-log - Log utilities

Tests

• Comprehensive vitest tests for all new modules
• Tests use real git repos for integration testing

Remaining Work (Future PRs)

• Phase 7: Bash Script Migration - Update cron scripts to use CLI commands
• Phase 8: Cleanup - Slim helpers.sh, delete bats tests

Test Results

• 544 tests passing (10 worktree tests skipped due to vitest fork pool limitation)
• yarn verify passes

Closes #57

🤖 Generated with Claude Code

[jonit-dev]

Night Watch PR Fix

Previous review score: N/A (review CI failed to run)

Changes made:

• Fixed no-dupe-else-if lint error in web/utils/cron.ts:200: added && hour.includes(',') to distinguish comma-separated hours from single-hour branch
• Confirmed worktree-manager.test.ts already has describe.skipIf(!isGitAvailable()) guard

CI Failures Fixed:

• lint: no-dupe-else-if in web/utils/cron.ts — two else if branches had identical conditions; first branch now checks hour.includes(',') to only match comma-separated hours
• test: CI was running on a stale merge commit; current branch already has the skipIf guard

yarn verify passes locally. Ready for re-review.

Night Watch PR Reviewer

[github-actions]

DiffGuard AI Analysis

AI Review Summary

🏆 Overall Score: 82/100

This PR implements a comprehensive CLI interface for cron script integration, replacing bash functions with well-structured TypeScript modules. The implementation is thorough with good test coverage, though there are a few concerns worth addressing.

✅ Key Strengths

• Comprehensive Implementation: Successfully replaces bash helper scripts with a complete TypeScript solution, covering lock management, PRD discovery, claim handling, and worktree operations
• Excellent Test Coverage: All new utility modules have thorough tests covering edge cases like stale locks, invalid JSON, missing dependencies, and cleanup scenarios
• Clean CLI Design: The cron command uses proper exit-code signaling for bash integration with well-organized sub-commands and consistent error handling patterns

⚠️ Areas for Improvement

• Code Duplication: The isClaimed and readClaimInfo functions in claim-manager.ts share nearly identical logic for parsing and validating claims. Consider extracting the common validation logic into a shared helper function.
• Silent Failures: Several modules silently swallow errors (e.g., getOpenBranches returns empty array on gh failure, git operations catch all errors). While this adds robustness, consider adding optional debug logging for troubleshooting production issues.
• Web Cron Fix Validation: The fix in web/utils/cron.ts adds && hour.includes(',') to conditionally handle comma-separated hours. Ensure this doesn't break single-hour cron expressions like 0 5 * * * which would now skip this branch entirely.

🐛 Bugs Found

Bug Name	Affected Files	Description	Confidence
Single-hour cron handling regression	web/utils/cron.ts	The added && hour.includes(',') condition may cause single-hour cron expressions (e.g., 0 5 * * *) to skip necessary hour adjustment logic, potentially returning incorrect next run times	🟡 Medium

🔧 Issues Found

Issue Type	Issue Name	Affected Components	Description	Impact/Severity
Performance	Redundant fetch in worktree preparation	worktree-manager.ts	prepareBranchWorktree calls git fetch before checking if branch exists locally, even when unnecessary	Low - Minor optimization opportunity
Testing	Missing CLI command integration tests	packages/cli/src/commands/cron.ts	While utility modules are well-tested, the CLI command handlers lack integration tests for argument parsing and exit code behavior	Medium - Consider adding basic CLI integration tests
Maintainability	Duplicated validation logic	claim-manager.ts	isClaimed and readClaimInfo both implement timestamp validation and stale claim removal independently	Low - Minor refactoring opportunity

🔚 Conclusion
The PR is well-executed with solid architecture and comprehensive testing. The primary concern is the web cron fix which should be verified against single-hour cron expressions. Addressing the minor code duplication and considering optional debug logging would further improve maintainability. The implementation is production-ready with minor adjustments.

---

Analyzed using z-ai/glm-5

[jonit-dev]

Additional Tests Added

New test coverage:

• findEligibleBoardIssue (prd-discovery.ts): 6 new tests covering empty output, gh failure, first unclaimed issue returned, claimed issue skipped, all claimed → null, malformed JSON skipped
• cron CLI subcommands (cron.test.ts): Tests for all subcommands covering exit-code signaling (0/1/2), invalid argument validation, and stdout output paths

Night Watch PR Reviewer

[github-actions]

DiffGuard AI Analysis

AI Review Summary

🏆 Overall Score: 88/100

This PR successfully implements CLI cron commands and supporting utilities to replace bash helper functions. The code is well-structured with comprehensive test coverage and clear separation of concerns.

✅ Key Strengths

• Clean Architecture: Well-organized utilities with focused responsibilities (claim management, git operations, worktree handling) that export clear interfaces
• Comprehensive Test Coverage: Tests for all new modules with proper mocking, edge case handling, and realistic scenarios including git operations
• Defensive Programming: Proper error handling, input validation, and automatic cleanup of stale claims/locks throughout

⚠️ Areas for Improvement

• Unrelated Formatting Changes: The roadmap-mapping.ts changes appear to be IDE auto-formatting (quote style changes from double to single quotes) unrelated to the PR's purpose. These should be reverted or separated into a dedicated formatting PR
• Incomplete Logic Fix in cron.ts: The condition change hour.includes(',') added to the hour parsing logic may break simple hour expressions like "0 5 * * *" (single hour without comma). This needs verification
• Silent Error Handling: Some utility functions silently catch errors (e.g., releaseLock, releaseClaim) which could hide filesystem permission issues during debugging

🐛 Bugs Found

Bug Name	Affected Files	Description	Confidence
Incomplete Hour Parsing Logic	web/utils/cron.ts	Adding hour.includes(',') to the condition may cause the else-if branch to be skipped for valid single-hour cron expressions (e.g., 0 5 * * *)	🟡 Medium

📋 Issues Found

Issue Type	Issue Name	Affected Components	Description	Impact/Severity
Testing	Race Condition Coverage	claim-manager.ts, status-data.ts	Lock/claim acquisition lacks tests for concurrent access scenarios	Low
Code Quality	Unrelated Changes	roadmap-mapping.ts	Formatting changes unrelated to PR purpose	Low
Performance	Repeated Git Calls	worktree-manager.ts	Multiple sequential git commands could be optimized into fewer calls	Low

🔚 Conclusion
The PR is well-executed with solid implementation of the cron command infrastructure. Addressing the hour parsing logic issue and reverting unrelated formatting changes would bring this to production-ready quality. The comprehensive test suite and clean utility design demonstrate good engineering practices.

---

Analyzed using z-ai/glm-5