---
phase: "17"
plan: "05"
subsystem: cli-commands
tags: [telegram, scheduler, gocron, cobra, serve, schedule, cron]
dependency_graph:
  requires: [bot-command-handlers, engine, storage, providers]
  provides: [serve-command, schedule-command, scheduler-engine]
  affects: [web-dashboard]
tech_stack:
  added: [github.com/go-co-op/gocron/v2@v2.19.1]
  patterns: [gocron-scheduler-with-db-backed-jobs, cobra-subcommand-crud]
key_files:
  created: [cmd/serve.go, cmd/schedule.go, pkg/scheduler/scheduler.go, pkg/scheduler/source.go, pkg/storage/scheduled_jobs.go, pkg/storage/scheduled_jobs_test.go]
  modified: [cmd/stubs.go, pkg/storage/schema.sql, go.mod, go.sum]
decisions:
  - "Scheduler runs inside serve command process; schedule add/list/remove/run are standalone DB operations"
  - "gocron v2 job registration uses CronJob with 5-field cron expressions"
  - "OnFindings callback on Scheduler allows serve to wire Telegram notifications without coupling"
  - "scheduled_jobs table stores enabled/notify flags for per-job control"
metrics:
  duration: 6min
  completed: "2026-04-06"
---

# Phase 17 Plan 05: Serve & Schedule CLI Commands Summary

**cmd/serve.go starts scheduler + optional Telegram bot; cmd/schedule.go provides add/list/remove/run CRUD for cron-based recurring scan jobs backed by SQLite**

## Performance

- **Duration:** 6 min
- **Started:** 2026-04-06T14:41:07Z
- **Completed:** 2026-04-06T14:47:00Z
- **Tasks:** 1 (combined)
- **Files modified:** 10

## Accomplishments
- Replaced serve and schedule stubs with real implementations
- Scheduler package wraps gocron v2 with DB-backed job persistence
- Serve command starts scheduler and optionally Telegram bot with --telegram flag
- Schedule subcommands provide full CRUD: add (--cron, --scan, --name, --notify), list, remove, run

## Task Commits

1. **Task 1: Implement serve, schedule commands + scheduler package + storage layer** - `292ec24` (feat)

## Files Created/Modified
- `cmd/serve.go` - Serve command: starts scheduler, optionally Telegram bot with --telegram flag
- `cmd/schedule.go` - Schedule command with add/list/remove/run subcommands
- `cmd/stubs.go` - Removed serve and schedule stubs
- `pkg/scheduler/scheduler.go` - Scheduler wrapping gocron v2 with DB job loading, OnFindings callback
- `pkg/scheduler/source.go` - Source selection for scheduled scan paths
- `pkg/storage/schema.sql` - Added scheduled_jobs table with indexes
- `pkg/storage/scheduled_jobs.go` - CRUD operations for scheduled_jobs table
- `pkg/storage/scheduled_jobs_test.go` - Tests for job CRUD and last_run update
- `go.mod` - Added gocron/v2 v2.19.1 dependency
- `go.sum` - Updated checksums

## Decisions Made
1. Scheduler lives in pkg/scheduler, decoupled from cmd layer via Deps struct injection
2. OnFindings callback pattern allows serve.go to wire Telegram notification without pkg/scheduler knowing about pkg/bot
3. schedule add/list/remove/run are standalone DB operations (no running scheduler needed)
4. schedule run executes scan immediately using same engine/storage as scan command
5. parseNullTime handles multiple SQLite datetime formats (space-separated and ISO 8601)

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Fixed parseNullTime to handle multiple SQLite datetime formats**
- **Found during:** Task 1 (scheduled_jobs_test.go)
- **Issue:** SQLite returned datetime as `2026-04-06T17:45:53Z` but parser only handled `2006-01-02 15:04:05`
- **Fix:** Added multiple format fallback in parseNullTime
- **Files modified:** pkg/storage/scheduled_jobs.go
- **Verification:** TestUpdateJobLastRun passes

**2. [Rule 3 - Blocking] Renamed truncate to truncateStr to avoid redeclaration with dorks.go**
- **Found during:** Task 1 (compilation)
- **Issue:** truncate function already declared in cmd/dorks.go
- **Fix:** Renamed to truncateStr in schedule.go
- **Files modified:** cmd/schedule.go

---

**Total deviations:** 2 auto-fixed (1 bug, 1 blocking)
**Impact on plan:** Both essential for correctness. No scope creep.

## Issues Encountered
None beyond the auto-fixed items above.

## Known Stubs
None. All commands are fully wired to real implementations.

## Next Phase Readiness
- Serve command ready for Phase 18 web dashboard (--port flag reserved)
- Scheduler operational for all enabled DB-stored jobs
- Telegram bot integration tested via existing Phase 17 Plan 03 handlers

## Self-Check: PASSED