CLI parity: design outline
Status: Initial implementation. See specification, source audit and tasks.
Existing logic audit
src/camply/cli/main.pyis a Click group with help/version, standalone and role serving, health checks, and lazydbresolution. Extend this group; do not replace its current commands.src/camply/providers/base.pyexposes validated asyncsearch/search_upstream,find_availabilitiesand metadata ingestion. Feature 025 provides database-independent discovery across 13 registered providers. It does not provide a complete public site/equipment/exact-ID resolution contract.src/camply/providers/dto.pysupplies typed discovery results and nightly site availability. Provider-native opaque string identities are already supported. Ticket/time-slot inventory and explicit equipment lengths need richer contracts.src/camply/db/availability.pyimplements shared web matching.src/camply/worker/engine/scanner.pywraps availability checks in persistentUniqueTarget, campground, subscriber eligibility, snapshot replacement and fan-out behavior. A local CLI search cannot callcheck_targetwithout inventing database users/scans.src/camply/worker/notificationscurrently contains base/Pushover delivery, and the standalone outbox provides durable retry semantics. Initial CLI delivery is console-only, so no notification extraction/adapter/credential resolver is needed. Keep existing web Pushover delivery unchanged; console results use direct provider links.pyproject.tomldeclarescli | server | workeras peer layers above providers/db. CLI cannot import worker engine or notification modules directly. Optional-free import contracts cover CLI/providers/db; adding imports is not sufficient to make shared worker code usable there.
Initial design outline
Scope follows the specification's D01–D13 registry. Historical replacement ideas in the audit are future options, not initial design obligations.
- Extend the current lazy Click group with provider listing, recreation-area/campground discovery and campground-based availability. Use existing Click/plain output; Rich-click, TUI and
configureare TODOs. Implement the specification's exact option/default/precedence contract and stdout/stderr behavior. Normalize CLI flags only; no YAML loader or legacy.camplymigration. Provider resolution must distinguish explicit Click parameters from environment/default values so a command-level environment fallback cannot override an explicit root selection. - Reuse feature 025's public provider search and current availability methods. Add database-independent exact campground metadata lookup and complete area/campground enumeration. Feature 025 has neither a campground-ID argument nor a public pagination cursor: do not pretend its limited
searchmethod supplies these contracts. Implement the smallest public provider capabilities required to resolve explicit IDs and enumerate all children, reusing native catalog/request logic. Keep the 50-result display limit, truncation detection and exhaustive availability expansion separate. Test exact IDs outside the displayed page and synthetic areas larger than the 1000-result validation cap. Do not introduce public site catalogs, site-ID resolution or equipment capabilities for deferred workflows. - Extract shared matching/stay construction only where needed by initial CLI/web reuse. External CLI notifications, including Pushover, are deferred; do not extract notification interfaces/adapters for this initial scope. A base-only
camply.corelayer is a proposed home, with dependency ordercli | server | worker→core→providers→db→__about__. Confirm the smallest useful extraction before creating it. Update exhaustive Import Linter contracts and architecture documentation together; no upward imports or blanket exceptions. - Keep persistent
check_target, web subscriber eligibility, locks, outbox and alert policy in their current adapters. Local checks should not fabricate users or require database migration/catalog ingestion. Use existing provider-native strings and complete area/campground targets, without accepting individual site selectors. - Design and test an internal availability-check operation with bounded async requests, provider pacing/retries, deduplicated targets, typed matching and owned-client cleanup. The public command performs the first check immediately and continues after matching/empty checks until cancelled, without legacy mode switches. A single internal check is a building block, not a public one-pass mode.
- Render results and provider booking links to the console only. Do not import/dispatch Pushover delivery, query database users, read notification credentials, create
PUSHOVER_USER_KEY, or add notification options/commands. Existing web notification modules/settings remain unchanged. CLI activation and credentials are future D03 design, along with all external channels, caps and history. - D11 remains open: intended default is search forever. Brainstorm command lifecycle, the need/meaning of the three old run-mode flags, pacing, stopping, expiry, cancellation outcomes and cron later. The initial default is immediate, continued checking until cancellation, including after a match; test that behavior through the public command. Detailed scheduling/failure/expiry/alert policy and the legacy flag matrix remain deferred. Do not carry forward the old flag-only one-pass default or implicit-continuous triggers as requirements.
Deferred design references
Keep the source audit and TODO backlog for later work. No initial shared schema, provider adapter or persistence layer is required solely for these items:
- D01/D02: site catalogs, individual campsite selection and site-to-parent lookup.
- D03: all external CLI delivery including Pushover, activation/credentials, full channel parity and test-notifications.
- D04: missing campground providers/catalogs, Yellowstone and all legacy GoingToCamp deployments/facade.
- D05/D10: YAML compatibility, legacy
.camplymigration and configuration wizard. - D06/D07: permits, tickets/tours/timed entry, slots/quantities and equipment catalogs/filtering.
- D08/D09: TUI and Rich-click.
- D12/D13: first-batch notification controls, persistent JSON history, offline flags and state migration.
Legacy deployment IDs, notification caps and YAML precedence remain documented facts. They are not promised future designs until their TODOs are revisited. General permit support is a requested future feature; the audited ticket/tour providers are not evidence of broader legacy permit support.
Constitution review
Use Python >=3.11, development/default CI 3.14, Pydantic v2 and async IO. Preserve one distribution and optional dependency independence. Any core extraction requires an intentional architecture/governance/import-contract review and negative boundary tests. Live observations remain the only availability authority. This scope requires no CLI history file, application database, frontend change or new inventory schema.
Delivery and validation
Initial order: scope/capability fixtures → current-provider discovery and internal availability checks → availability command with search-forever as the default direction and console-only output → initial release gates. D11 is a later brainstorming item for detailed modes/flags. Deferred TODOs are not initial release gates or follow-on implementation authorization.
Use Click runner tests for every public option, precedence and validation rule, synthetic HTTP contracts for current providers, matching/stay fixtures and installed wheel/sdist checks on Python 3.11/3.14. Verify current provider aliases/identities and unsupported inputs without requiring all historical deployment/channel mappings to execute. Protect existing serve/db/standalone/distributed behavior and optional-free imports. The minimum public-command monitoring/cleanup tests below are initial acceptance gates; only additional D11 policies wait for later design. YAML/state/permit/equipment/TUI/new-channel tests wait for their TODOs.
Implementation gates: task test, task check, task lint, appropriate installed-artifact tasks and task docs:check.
Implementation decisions
- Command ownership is split across
camply.cli.serve,db,providers,recreation_areas,campgroundsandcampsites;maincontains only the root command and lazy routing.optionscentralizes reusable Click options without loading providers or database configuration. Shareddiscovery,outputandexecutionmodules handle resolution, rendering and cancellation respectively; commands never import the root router. camply.core.searchis the smallest shared foreground adapter. It reuses the existingcamply.db.availability.matching_available_datesfunction, so web matching needs no relocation or behavior change. The explicit exhaustive import order iscli | server | worker→core→providers→db→__about__; core is included in optional-free and package-root contracts, with negative boundary tests.BaseProvider.get_campground,get_recreation_areaanditer_campgroundsresolve exact metadata and complete eligible targets without a database. Complete catalogs back UseDirect/GoingToCamp; Recreation.gov and ReserveAmerica exhaust native pagination independently of the public discovery limit. All target resolution completes before availability checks.- The CLI owns and closes one provider client; sequential awaited operations bound concurrency and prevent duplicate overlapping checks. Existing HTTP pacing/retry/circuit-breaker behavior is reused. SIGINT/SIGTERM cancellation unwinds owned resources.
- Successful cycles use a provisional internal 60-second wait with a test seam. This adds no public scheduling option or settled D11 lifecycle policy. Provider failures remain errors, and no persistence, notification or legacy mode machinery is introduced.
Public command acceptance strategy
- Parameterized Click runner tests exercise actual command dispatch and normalization: canonical provider names/aliases, command/root/environment/default conflicts, explicit no-debug, repeated selectors/date pairs/weekdays, unknown IDs and deferred options. Assert provider request arguments and output streams; do not call only the normalized-request constructor.
- In isolated base wheel and sdist-rebuilt-wheel environments, run the installed
camplyexecutable from a temporary directory outside the checkout. Use synthetic local upstream HTTP responses through provider client/endpoint test seams; do not import repository source or replace the command callback/runner. The HTTP transcript must prove supplied IDs/windows reached the provider. No live booking service or real notification credentials are needed. - Script a first matching response and a subsequent successful response. Verify printed stays, a second completed request cycle and that the process has not exited after the match. Use an injected clock/wait seam for deterministic in-process tests and a bounded test cadence for the subprocess fixture; no user-facing test-only cadence flag is needed. Tests must not wait for a production polling interval.
- Send Ctrl-C/SIGTERM in subprocess tests and assert termination with no orphan polling. Separately instrument in-process client/task ownership and assert closure/cancellation and no scheduled requests after stop. A kill/timeout is test cleanup, not evidence the application shut down correctly. Do not prescribe deferred signal exit codes or detailed expiry behavior through these tests.
- Assert console results with notification settings absent/malformed and zero external-notification requests, database-user reads or delivery dispatch.
--notifications pushoverandtest-notificationsmust fail as deferred inputs; existing web notification regressions remain green. - Invalid dates/constraints, conflicting selectors under the documented precedence, missing required inputs and unsupported/deferred switches must be observed at the public parser/resolution boundary. Failures cannot be hidden by internal-operation tests passing.