pitboard_core/lib.rs
1//! The engine behind Pitboard: parking and restoring a person's own Claude Code and Codex
2//! logins, and reading what each has left. It serves Pitboard's own front ends, the command
3//! line and the native apps, which reach it through [`service::Pitboard`] with an explicit
4//! [`context::Context`].
5//!
6//! # What is supported
7//!
8//! This crate is published because the `pitboard` binary depends on it, not because it was
9//! designed for other programs to build on. The supported interface is [`service::Pitboard`],
10//! [`context::Context`], and the types those two return. Everything else is reachable so the
11//! front ends in this repository can reach it, and may change in any release.
12//!
13//! What a version promises, for the part that is supported: a code is a name, and names are
14//! kept. Adding an error, warning or check code is not a breaking change, which is why every
15//! enum a caller reads codes out of is `#[non_exhaustive]` and every such caller needs a
16//! fallback arm. Renaming or removing a code is a breaking change: a new minor version
17//! while Pitboard is at 0.x, as Cargo reads one, and a new major version after 1.0.
18//! A report a caller reads, such as what `uninstall` returns, may likewise say more in a
19//! later release, so those structs are `#[non_exhaustive]` too.
20//!
21//! What is deliberately not reachable: nothing outside this crate may write Pitboard's index.
22//! Every change goes through [`switch`], which records what it is about to do first and
23//! finishes an interrupted one before starting another.
24
25// Pitboard for Windows is being built, and reaches people only once the command line, the
26// app, their installers and their docs are done. Until then a Windows build of a release
27// compiles and refuses everything at run time (`release`). It compiles only for the two
28// targets its builds are made and tested on: an x64 or ARM64 PC with the MSVC toolchain.
29// A 32-bit, GNU, UWP or Arm64EC build is another program nobody has run.
30#[cfg(all(
31 windows,
32 not(all(
33 target_vendor = "pc",
34 target_env = "msvc",
35 any(target_arch = "x86_64", target_arch = "aarch64")
36 ))
37))]
38compile_error!(
39 "Pitboard for Windows is built for x86_64-pc-windows-msvc and aarch64-pc-windows-msvc \
40 alone, the targets it is built and tested on."
41);
42
43#[cfg(not(any(target_os = "macos", target_os = "linux", windows)))]
44compile_error!(
45 "Pitboard runs on macOS, Linux and Windows. Another system needs a host of its own in \
46 `host/`, saying where its stores, processes and scheduler are."
47);
48
49pub mod api;
50pub mod app;
51pub mod assumptions;
52pub mod audit;
53pub mod autoswitch;
54pub mod budget;
55pub mod context;
56pub mod doctor;
57pub mod duty;
58pub mod error;
59pub mod in_use;
60pub mod label;
61pub mod pace;
62pub mod provider;
63pub mod redact;
64pub mod release;
65pub mod schedule;
66pub mod service;
67pub mod settings;
68pub mod state;
69pub mod status;
70pub mod statusline;
71pub mod switch;
72pub mod time;
73pub mod usage;
74pub mod warm;
75pub mod words;
76
77pub(crate) mod atomic;
78pub(crate) mod fault;
79pub mod holder;
80pub(crate) mod home;
81pub mod host;
82pub(crate) mod lock;
83pub(crate) mod park;
84pub(crate) mod pending;
85pub(crate) mod proxy;
86pub(crate) mod readings;
87pub(crate) mod sessions;
88/// The program the tests start in place of a tool, reached as `testing::stand_in`. Its own
89/// tests run with the core's.
90#[cfg(any(test, feature = "test-support"))]
91#[doc(hidden)]
92pub mod stand_in;
93pub(crate) mod store;
94
95/// What the integration tests reach into: they plant and inspect parked logins in the real
96/// store, and must never touch the credential slot this machine's Claude Code reads.
97#[cfg(feature = "test-support")]
98#[doc(hidden)]
99pub mod testing {
100 pub use crate::api::scripted::{Answer, Asked, ScriptedApi, Trouble};
101 /// What a test or a fixture does to a file's access, or to make a link, which only this
102 /// system's face says how to do: the integration tests and the apps' fixtures do it here,
103 /// as the core's own tests do.
104 pub use crate::host::fs::testing as fs;
105 pub use crate::host::memory::MemoryHost;
106 pub use crate::provider::claude::paths::live_service;
107 pub use crate::provider::claude::slot::{LIVE_SERVICE, dir_hash, service_for_dir};
108 /// The program the integration tests, the model's tests and the fixtures' tests start in
109 /// place of `claude`, `codex` and every other program they run, on every system.
110 pub use crate::stand_in;
111 pub use crate::store::memory::{Fault, MemoryStore};
112 pub use crate::store::vault_read;
113 pub use crate::switch::{ScriptedSignIn, SignInScript};
114 pub use crate::time::{Clock, FixedClock};
115 pub use crate::warm::run::{Ran, Started, WarmScript};
116
117 /// Every variable Pitboard reads from its environment, by name, which a test withholds
118 /// from every command it runs unless it means to pass one on.
119 pub fn variables() -> impl Iterator<Item = &'static str> {
120 crate::context::variables()
121 }
122
123 pub fn real_login_places(
124 started_in: &crate::context::Context,
125 ) -> Result<Vec<std::path::PathBuf>, String> {
126 use crate::host::user;
127 let home = user::accounts_own_home().ok_or("this system names no home for this account")?;
128 let pitboard = user::accounts_own_pitboard_home()
129 .ok_or("this system names no Pitboard folder for this account")?;
130 let own = crate::context::Context::new(home).with_pitboard_home(pitboard);
131 Ok([&own, started_in]
132 .into_iter()
133 .flat_map(|ctx| {
134 [
135 crate::provider::claude::paths::config_dir(ctx),
136 crate::provider::claude::paths::config_file(ctx),
137 crate::provider::codex::paths::home(ctx),
138 ctx.pitboard_home.clone(),
139 ]
140 })
141 .filter(|place| place.is_absolute())
142 .collect())
143 }
144
145 /// Parks `contents` under `service` in this context's vault, as a change does, once the
146 /// gate every change passes has let it: a test that runs as root is refused here too.
147 pub fn vault_write(
148 ctx: &crate::context::Context,
149 service: &str,
150 contents: &str,
151 ) -> crate::error::Result<()> {
152 let permit = crate::service::gate(ctx)?;
153 Ok(crate::store::vault_write(ctx, permit, service, contents)?)
154 }
155
156 /// Deletes what is parked under `service`, once the gate has let it.
157 pub fn vault_delete(ctx: &crate::context::Context, service: &str) -> crate::error::Result<()> {
158 let permit = crate::service::gate(ctx)?;
159 Ok(crate::store::vault_delete(ctx, permit, service)?)
160 }
161
162 /// A sign-in to `which`'s tool that finished with `document`, the login the tool would
163 /// have stored, as JSON, and never ran the tool: what enrolling a second account by
164 /// signing in privately needs, in a test that may run no tool. Made once the gate has let
165 /// it, as every sign-in is.
166 pub fn signed_in(
167 ctx: &crate::context::Context,
168 which: crate::provider::ProviderId,
169 document: &str,
170 ) -> crate::error::Result<crate::switch::SignIn> {
171 let document = serde_json::from_str(document).expect("a login a test wrote as JSON");
172 crate::switch::planted(ctx, crate::service::gate(ctx)?, which, document)
173 }
174}