cratefield-cli 0.7.5

The fz CLI for Cratefield ventures: migrations collect/apply, doctor, modules, push
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

[package]
name = "cratefield-cli"
description = "The fz CLI for Cratefield ventures: migrations collect/apply, doctor, modules, push"
readme = "README.md"
keywords = ["cratefield", "cli", "migrations", "wrangler", "d1"]
categories = ["command-line-utilities", "development-tools"]
include = ["src/**/*", "examples/**/*", "README.md"]
version = "0.7.5"
edition.workspace = true
rust-version.workspace = true
license.workspace = true
repository.workspace = true

[lints]
workspace = true

[features]
# `fz migrations apply --dialect postgres` (issue #18): pulls the
# native-only Postgres adapter and a tokio runtime to drive it. Opt-in so
# the default fz dependency graph stays free of sqlx and tokio — a
# venture's wasm build must never see them.
postgres = ["dep:cratefield-adapter-postgres", "dep:tokio", "dep:cratefield-introspect"]
# `fz push send`'s network leg (issue #184): the runtime's own HTTP client —
# reqwest behind the outbound policy — and the tokio runtime it needs. Opt-in
# for the same reason `postgres` is, and the live-proof tool is documented as
# needing it (README, issue #186).
#
# A feature-gated *send* is not the feature-gated *doctor* the push-wiring
# note below refuses. The difference is what an `fz` without the feature
# does: `fz push send` says, in one line, exactly what to rebuild, while a
# doctor compiled without a check reports a clean bill and says nothing. Loud
# absence is a build option; silent absence is not. Everything else under
# `fz push` — keygen, inspect-subscription, and `send --dry-run`, which
# reports the transport's wiring — works in every build.
#
# This is never a feature a **venture** turns on: `cratefield-runtime-native`
# `compile_error!`s on wasm32 and a generated venture depends on this crate
# beside a wasm `cdylib`, so flipping it there breaks the build of the thing
# the venture deploys. A send-capable `fz` is installed separately
# (`cargo install cratefield-cli --features push-send`) and the Docker image
# is built with it.
#
# It pulls the whole native runtime — axum, redis, croner,
# tracing-subscriber — to obtain one `ReqwestClient` and one `TokioClock`,
# and the alternative was weighed: an `http-client` feature on
# `cratefield-runtime-native` that carried the ports without the server.
# Not taken, deliberately.
#
#   - That crate's module graph is not separable along that line today.
#     `ports/mod.rs` itself is built on axum types (`HeaderMap`,
#     `HeaderName`, the client-IP resolution the server middleware calls),
#     so an `http-client` build would have to `cfg` the ports module, the
#     runtime, the server, cron and the tracing setup — and every one of
#     those becomes a configuration nothing in CI compiles unless a matrix
#     leg is added for it.
#   - The cost it buys back is build time for one native binary that is
#     compiled once and installed. Nothing ships this graph: the venture's
#     wasm build never sees this crate (that is what the `compile_error!`
#     enforces), and the image already carries a Rust toolchain.
#   - The point of the live proof is that the send goes through *the
#     client the runtime uses*, wired the way `serve()` wires it. A leaner
#     dependency edge that reached a differently-assembled client would
#     make the proof prove less.
#
# Revisit it if a second consumer wants the same thing, which is when the
# split stops being a change made for one caller.
push-send = ["dep:cratefield-runtime-native", "dep:tokio"]
# `fz auth import`'s network leg (issue #650): the same native runtime
# client `push-send` reaches, for the same reason — the default `fz` graph
# carries no HTTP client, and `cratefield-runtime-native` `compile_error!`s
# on wasm32, so a venture must never turn this on. Without it the command
# says exactly what to rebuild (the `push-send` rule above, issue #191).
auth-import = ["dep:cratefield-runtime-native", "dep:tokio"]
# `fz import supabase inspect` (issue #658, ADR 0026): the Supabase
# importer's engine reads Postgres through sqlx, and its Management API and
# `--classify` legs go through the native runtime's reqwest client — the
# same client `push-send` uses, for the same reasons. Off by default for the
# reason `postgres` and `push-send` are: a venture's wasm build must never
# see sqlx, tokio or reqwest. An importing `fz` is installed separately
# (`cargo install cratefield-cli --features import-supabase`); without the
# feature the command still parses and says exactly that.
#
# It also enables `auth-import`: `fz import supabase users` (issue #659)
# sends the users it reads through `fz auth import`'s own batch seam, so the
# feature that pulls sqlx also needs the HTTP client and the tokio runtime
# that seam uses (both already in this list).
import-supabase = [
    "dep:cratefield-import-supabase",
    "dep:cratefield-runtime-native",
    "dep:cratefield-adapter-typesafe",
    "dep:tokio",
    "auth-import",
]

[dependencies]
cratefield-core = { workspace = true }
cratefield-adapter-sqlite = { workspace = true }
# `fz doctor` reads the push environment through the same `build_push` the
# runtimes do (issue #191), so the doctor and `serve()` cannot check different
# variable names. Pure Rust and native-safe: the push adapters speak HTTP
# through the `HttpClient` port and pull no tokio, sqlx or OpenSSL.
#
# **Not** optional, unlike `postgres` below, and the difference is deliberate.
# `fz` is built once and installed; a feature-gated doctor check is a doctor
# that silently checks less depending on how somebody's `fz` was compiled,
# which is the same class of invisible drift this crate exists to remove. The
# cost is that every `fz` links the three adapters and their crypto, and that
# `cratefield-push-wiring` must be first-published before `cratefield-cli`
# (docs/RELEASING.md).
cratefield-push-wiring = { workspace = true }
# `fz push vapid keygen` (issue #184) mints the P-256 key pair with the same
# signer the adapters present their provider tokens with, so the public half
# it prints is the one `WebPush::public_key()` derives — not a second
# derivation that could disagree about the point encoding.
cratefield-push-auth = { workspace = true }
# `fz push inspect-subscription` validates with the Web Push adapter's own
# rules — `vapid::origin_of` for the audience, `ece::SubscriptionKeys` for
# the two keys — so a subscription the CLI accepts is one the adapter
# accepts. Already in the graph through `cratefield-push-wiring`; named here
# because this crate calls it directly.
cratefield-adapter-webpush = { workspace = true }
cratefield-manifest = { workspace = true }
clap = { workspace = true }
base64 = { workspace = true }
# The VAPID scalar and its base64url form are key material: cleared on drop,
# the workspace convention (`crates/kms`, `crates/secrets`, the adapters).
zeroize = { workspace = true }
# Draws the VAPID private scalar. Backend selection is the final crate's job
# in this workspace, which for a native-only binary is the default one; the
# line matches `cratefield-kms` and `cratefield-push-auth`.
getrandom = { workspace = true }
toml = { workspace = true }
sha2 = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
# `fz auth import` builds its request (`http::Request<Bytes>`) directly
# against the `HttpClient` port's own types, the same vocabulary the
# adapters and `fz push` speak. Pure types, no client: the network leg
# stays behind `auth-import`.
http = { workspace = true }
bytes = { workspace = true }
tracing = { workspace = true }
pollster = { workspace = true }
sea-query = { workspace = true }
cratefield-adapter-postgres = { workspace = true, optional = true }
# `fz tables drift` reads the target database's catalog (issue #153).
# Optional for the same reason the adapter is: it is only reachable on
# the direct-connection flow.
cratefield-introspect = { workspace = true, optional = true }
# The declaration vocabulary both `fz tables` subcommands print, and the
# diff one of them runs. Not optional and not behind `postgres`: comparing
# two manifests needs no database, and the crate carries no I/O and no
# driver of its own.
cratefield-tables = { workspace = true }
# `fz client-ts` (issue #155) hands the `/__surface` document to the
# generator and writes the files it returns. Versioned through
# `[workspace.dependencies]` since 0.6.0 (#558): the crate is publishable
# now, so the packaged CLI resolves this edge on crates.io.
cratefield-client-ts = { workspace = true }
# `push-send` only: the native runtime's reqwest client and its outbound
# policy. Native-only by construction (the crate refuses to compile on wasm),
# which is why it is optional and off by default.
cratefield-runtime-native = { workspace = true, optional = true }
# `import-supabase` only: the engine, and the TypeSafe `Classifier` adapter
# `--classify` builds through its own `from_env`.
cratefield-import-supabase = { workspace = true, optional = true }
cratefield-adapter-typesafe = { workspace = true, optional = true }
# `net` and `time` on top of the workspace pin: reqwest needs the IO and
# timer drivers enabled, and `enable_all()` silently enables neither without
# them — a runtime that then panics on the first request.
tokio = { workspace = true, optional = true, features = ["net", "time"] }

[dev-dependencies]
# The push unit tests send through a scripted `HttpClient` rather than the
# network. Path-only: `cargo publish` resolves dev-dependencies against
# crates.io (the workspace manifest's note), and a path-only one is stripped
# from the packaged manifest.
cratefield-testing = { path = "../testing" }