Crate djogi_cli 

Djogi CLI library — entry points for the djogi binary and for adopter-linked binaries that inject their own DescriptorProvider. The published standalone djogi binary links no adopter model crates, so reading the global inventory registry directly yields zero adopter models. Injecting a DescriptorProvider lets an adopter-linked binary supply its own models. See run_with_provider.

Macros

djogi_main

Generate a fn main() that references model types to prevent the LTO linker from dropping inventory data, then delegates to djogi_cli::run_from_env(). Referencing a single descriptor per crate forces ALL inventory from that crate into the final binary. This macro makes that reference explicit and auditable at the adopter’s binary entry point.

link_anchor

Emit a once-per-crate linkage anchor so an adopter binary can force link-time retention of THIS crate’s #[derive(Model)] registrations without listing every model type (#370, branch b).

Structs

Cli

InventoryDescriptorProvider

The link-time inventory-backed DescriptorProvider — the only shipped implementation.

TableHealth

Snapshot of a single table’s vacuum / partition health. Field provenance (per the live-DB query plan):

Enums

AnalyzeError

Errors surfaced by run / fetch_table_health. Each variant carries operator-actionable context — the goal is that an eprintln!("djogi analyze: {e}") line is enough to diagnose without grepping source. Mirrors verify::VerifyError’s shape.

AnalyzeFormat

Output format for djogi analyze — clap-side mirror of [analyze::AnalyzeFormat]. This enum exists only so clap::ValueEnum can derive the --format human|json parser without dragging the clap-derive dependency into the analyze module’s pure-substrate header. Conversion to the canonical [analyze::AnalyzeFormat] happens at the dispatch site via Self::into_analyze.

DbCommand

LiveCmd

Operator surface for the live-migration runner. Every subcommand resolves to an ExitCode via dispatch.

LiveCmdError

Errors raised by the live subcommand. Each variant carries a dedicated exit-code mapping; conversion lives in LiveCmdError::exit_code. #[non_exhaustive] so future failure modes (e.g. a daemon-mode claim conflict) can land without breaking downstream matches.

MigrateCommand

MigrationsCommand

PartialApplyResolutionCli

CLI-side mirror of djogi::migrate::PartialApplyResolution for the repair partial-apply resolution argument. This enum exists only so clap::ValueEnum can parse rolled-back | faked | applied at the CLI boundary without the library enum carrying a clap-derive dependency. Conversion to the canonical djogi::migrate::PartialApplyResolution happens via the From impl in the migrations module.

Recommendation

Recommendation produced by recommend for a single table.

RepairSubcommand

djogi migrations repair <subcommand> — the four operator-confirmed repair flows. Each variant maps 1:1 onto a djogi::migrate::repair::* library function. Invoking the subcommand IS the operator acknowledgment; there is no separate --confirm flag. Every flow pins one Postgres session, takes the per-bucket advisory lock, and holds the workspace file lock for its duration. Exit codes (shared across all four): 0 success, 1 runtime/I/O error (retryable), 2 refusal or structural mismatch (operator must intervene).

SchemaError

Errors surfaced by [run].

SchemaFormat

Output format for djogi schema. Mirrors [schema::SchemaFormat] so clap::ValueEnum lives at the CLI boundary and the schema module stays clap-free.

TopCommand

VerifyError

Errors surfaced by [run]. Each variant carries enough context for an operator to act without grepping source — the I/O variants name the path, the key-decode variant carries the underlying SnapshotKeyError, and the audit-pool variant records the URL we failed to reach.

Traits

DescriptorProvider

Source of the #[derive(Model)] descriptors a descriptor-dependent command operates on.

Functions

apply_cmd

djogi migrations apply entry point. Discovers pending JSON files under target/djogi_pending/, loads the committed replay plan for each, and drives djogi::migrate::apply_plan through the library runner after CLI-side ledger-state classification. Pending rows require operator resolution. Caller-gated Failed/RolledBack rows are reapply-blocking cleanup candidates before runner invocation. Phase 0 cleanup is identity-free replay-current-only: seed-capable runtime, seed-DML non-runtime-current, missing, incomplete, generated-stale, or ambiguous artifacts refuse before delete.

attune_cmd

djogi migrations attune entry point. Mode selection (per CLI flags):

baseline_cmd

djogi migrations baseline entry point. Establishes a baseline ledger row + snapshot for an existing database adopted under Djogi’s migration ledger. The schema already exists, so compose + apply cannot run against the populated database without a starting point; baseline projects the live catalog into a single baseline ledger row (no SQL runs against user tables) and persists the projected snapshot as the canonical baseline so future migrations diff against the real DB state. --reason is required and must be non-empty — it is recorded in the ledger row’s partial_apply_note for the audit trail. An empty reason is a refusal (exit 2) caught before any DB work. Exit codes: 0 success, 1 runtime error (config / pool / projection failure), 2 refusal (empty --reason, unresolvable database URL, duplicate version collision, snapshot-persist failure after ledger insert, session-pinning correctness failure, or below PG 18).

cleanup_test_dbs_cmd

djogi db cleanup-test-dbs entry point — drops orphaned djogi_test_<uuid> databases left behind by #[djogi_test] runs killed by SIGKILL / OOM / panic-after-spawn before djogi::testing::teardown_test_db could fire. Triple-gated identical to db reset:

compose_cmd

djogi migrations compose entry point.

dispatch

Top-level entry point invoked by [crate::main]. Builds a runtime, drives the async dispatch, and folds the resulting LiveCmdError to an ExitCode via LiveCmdError::exit_code.

docs_cmd

djogi docs entry point. output defaults to target/djogi-docs/ under the workspace. The per-model files are written into <output>/<app>/<Model>.md and a top-level <output>/README.md indexes them.

fetch_table_health

Pull live-DB stats from pg_stat_user_tables and (optionally) pg_partman.show_partitions(...) for every user table.

print_support_boundary_error

Print a support-boundary preflight error to stderr. Used by every CLI entry point that runs check_postgres_version. The “support boundary” prefix distinguishes infrastructure refusals (wrong PG version, missing extension) from policy refusals (localhost gate, production profile) and runtime failures (SQL error, network).

recommend

Pure recommendation function for a single table.

refuse_offline_only

Refuse the live-plan compose path when the delta carries an OfflineOnly operation. Hoisted into a free function so the future live plan engine wires it in by importing this helper rather than re-deriving the message shape; the wider call surface here surfaces the variant in the public API for the LiveCmdError::exit_code() contract (exit 2). Returns LiveCmdError::ClassificationRefused which maps to exit code 2 per of the plan.

repair_checksum_drift_cmd

djogi migrations repair checksum-drift entry point. Updates the checksum_up / checksum_down columns of an already-applied ledger row after its committed SQL was edited. When --checksum-up / --checksum-down are omitted, the checksums are recomputed from the committed files on disk (a missing down file is a no-op; any other read error aborts with exit 1).

repair_cmd

djogi migrations repair <subcommand> entry point. Routes each subcommand to its glue function. The glue functions own the runtime / config / pool / lock / report-render lifecycle; this router only destructures the parsed clap variant.

repair_partial_apply_cmd

djogi migrations repair partial-apply entry point. Resolves a partial-apply ledger row by rewriting its status to rolled_back, faked, or applied. No SQL executes — only the ledger row is mutated.

repair_resume_partial_apply_cmd

djogi migrations repair resume-partial entry point. Resumes an interrupted non-transactional apply by loading the committed <version>.plan.json and replaying its remaining steps. Loads the committed plan directly (no CLI-level checksum pre-gate); the library validates the plan against the ledger row internally.

repair_snapshot_rebuild_cmd

djogi migrations repair snapshot-rebuild entry point. Rebuilds a bucket’s schema snapshot by walking the ledger and re-projecting from live database state. When --snapshot-path is omitted, the path is derived from migrations/<database>/<app>/schema_snapshot.json.

reset_cmd

djogi db reset entry point. yes: when true, the function does NOT prompt the operator the request flows straight into reset_app_database. When false, the function prints a y/N prompt to stderr and reads stdin; only an explicit y / yes answer (case-insensitive) proceeds. Any other input refuses with the standard ResetRefusal::NotConfirmed exit code. maintenance_database defaults to "postgres" — the conventional administrative DB present on every cluster — when the operator supplies nothing more specific.

run

djogi analyze entry point — consumed by main.rs::TopCommand::Analyze. Orchestrates the live-DB pull, the pure recommendation pass, and the rendering. Splitting fetch / recommend / render this way means every test (unit, integration, regression) targets exactly the layer that interests it without dragging in the others.

run_from_env

Run the CLI by parsing arguments from std::env::args_os(). This is the entry point used by the published standalone djogi binary. It reads the global link-time inventory registry via djogi::migrate::InventoryDescriptorProvider.

run_with_args

Run the CLI with an explicit argument iterable. Useful for testing and embedding. Accepts any IntoIterator<Item = T> where T: Into<OsString> + Clone, matching the bound of clap::Parser::try_parse_from. In practice, arrays of &str (e.g. ["djogi", "migrations", "compose"]) and Vec<String> both satisfy this bound. Falls back to djogi::migrate::InventoryDescriptorProvider for descriptors.

run_with_provider

Run the CLI with an explicit argument iterable and a DescriptorProvider. Accepts any IntoIterator<Item = T> where T: Into<OsString> + Clone, matching the bound of clap::Parser::try_parse_from. Adopter-linked binaries pass their own provider so descriptor-dependent commands (compose, verify, schema, docs) see the adopter’s models instead of an empty inventory.

seed_cmd

djogi db seed entry point.

status_cmd

djogi migrations status entry point. Read-only — does not acquire the workspace lock. Reads the migration ledger from the active database via djogi::context::DjogiContext.

verify_cmd

djogi migrations verify entry point. Read-only — does not acquire the workspace lock. Reads the live Postgres catalog via djogi::context::DjogiContext and compares against the projected schema from the descriptor inventory. Exit codes: 0 on success (no error-level diagnostics), 1 on runtime error (config / network / SQL / projection), 2 on refusal (below PG 18).