nimbus-core
Session/vault-management logic shared by nimbus's frontends (nimbus-cli and
nimbus-tui). Owns the App — registered vaults, the current vault/working directory,
and the local staging vault — plus the on-disk config App is built from. Frontends drive it
through App's methods and are responsible for their own input/output loop; nimbus-core has no
terminal/UI code of its own.
What's here
-
config.rs—CliConfig: the on-disk shape read from<config>/.nimbus/cli_config.toml(default_local_vault, defaulting totrue;local_vault_path, defaulting to$HOME). The directory comes fromnimbus_vault::config_home()rather than being rebuilt here, so the CLI config and the vault configs written bynimbus-creatorcan't drift apart.CliConfig::load()returns the default config if the file doesn't exist yet, rather than erroring. -
app.rs—App: holds every registeredVault(by name), the specialLOCALvault (the user's own filesystem, whendefault_local_vaultis enabled), the current vault/cwd, and vault-config paths so they can be re-registered on the next run.App::init()loadsCliConfig, opens the vaults registered in<state>/nimbus/session.toml, and (re-)registersLOCALif configured.App::save()writes that session file back.The session path is a field (
state_path), not a constant, so tests can point it at a scratch file. That isn't stylistic:save()used to write the real session file unconditionally, socargo testrewrote the developer's own vault registry.
The session file
SavedState holds three things: vault_configs (the name → config path registry),
current_vault, and cwd_path. The last two are what let a one-shot nimbus-cli ls pick up
where the previous nimbus-cli cd docs left off. Both are #[serde(default)], so session files
written before they existed still load.
Restoring the directory can't happen in init(): turning a path back into an ObjectId means
walking it with one Vault::find per component, which is async and reaches the origin, and
init() is a sync constructor. So init() parks what it read in a private field and
App::restore_session() (async) applies it. Frontends that want the behaviour call it right
after init(); ones that don't (the TUI opens on its own vault picker) simply don't.
Two rules protect the session from being destroyed by a transient failure:
- A vault whose config doesn't build right now is warned about and skipped for the session,
but stays in the registry. Config building can fail for reasons that aren't permanent — an
[origin_config.auth]whosetoken_envisn't exported in this shell — and dropping the entry would have the nextsave()unregister the vault for good.open_vaultstherefore borrows the registry instead of consuming it, andforget_vaultchecks the registry, so a vault that can't be opened can still be unregistered. save()leaves a session that was read but never restored (a frontend that skipsrestore_session) exactly as it found it, rather than overwriting it with the root. Otherwise opening the TUI would wipe the CLI's position.
restore_session degrades rather than failing: a vault that's gone leaves you at the app root, a
directory that's gone leaves you at that vault's root (select has already put you there), each
with a warning on stderr.
Commands exposed by App
ls, vaults, select, new_vault, forget_vault, cd (plus cd_completions, used by
nimbus-cli's tab completion), put, get, mkdir, touch, rename, cp, mv, delete,
push, pull, exit. See crates/cli/README.md for the user-facing
command reference these map to. restore_session sits alongside them but isn't a user command —
it's the async half of init, described above.
exit is the odd one out: it save()s and then calls std::process::exit(0) itself, rather
than reporting back that the frontend should shut down. nimbus-tui therefore never routes its
own quit through it — it has an event loop and a terminal to restore first.
Alongside those are data-returning methods, for frontends that render rather than print:
vault_names(), list_cwd(), fetch_object_bytes(id) and write_object_bytes(id, bytes). The
last two are what let the TUI open a file in an editor and save the result back.
put/get/cp/mvall follow the same pattern: resolve the source path to anObjectIdviaVault::find,getitsObject,putit under the resolved destination, and — forLeafs only —fetchthe payload from the source andsendit to whateverObjectputreturned (not the pre-putobject; seecrates/vault/README.md).put/getadditionally resolve local-filesystem paths throughresolve_local_path, which canonicalizes the input and rejects anything outside the configured local root — this is the boundary that keepsLOCALfrom touching files outsidelocal_vault_path.getwith no destination targets the local vault's root, not the process's working directory, which would otherwise fail anywhere except inside the local root.cdwith no vault selected treats the path's first component as a vault name (selects it) and recurses on the remainder; with a vault selected, it resolves the path relative to the current directory viaVault::find.
Path specs
resolve_spec is how nearly every command turns a typed argument into a (vault, absolute path)
pair:
| Spec | Resolves to |
|---|---|
notes.txt |
relative to cwd_path, in the current (or explicitly named) vault |
/docs/notes.txt |
absolute within that vault |
backup:/inbox |
the vault named backup, from its root |
split_vault_spec only treats a name: prefix as a vault when name is actually registered, so
an object whose name contains a colon still resolves as a path. A qualified spec resolves from
that vault's root because there is no meaningful "current directory" in a vault you aren't
standing in.
Recursion, renaming, and the guards
deep_copyis what makescp/mv/renamework on directories.Vault::puton aBranchonly creates the entry itself — it knows nothing about children — so without recursion a moved directory would arrive empty and the source would then be deleted. It takes an optionalrename_to, which applies to the top level only; descendants keep their own names.renameis a copy under the new name followed by deleting the original, becauseOriginhas no rename primitive (putalways writes an object under its ownget_name()). Correct for every origin, but it costs a full data copy — worth knowing for a large object on a remote origin. A realOrigin::renamewith anfs::renamefast path is the fix if that ever matters.cp/mvdestinations may be an existing directory (the object keeps its name) or a path that doesn't exist yet (it lands in its parent under that new name). An existing file is refused rather than overwritten, becauseputtruncates.- The into-itself guard rejects any destination whose path starts with the source's, with no
exemption for the two being equal — pasting a directory into itself resolves to exactly that,
and
deep_copywould otherwise recurse into the copy it had just made, forever.starts_withis component-wise, socp a.txt a.txt.bakandcp docs docs2are unaffected. deleterefuses a non-empty directory unless forced. The check only runs for directories: asking an origin to list a leaf is an error, not an empty listing, so applying it universally made every file undeletable without--force.new_vaultrefuses a name already registered to a different config path — silently replacing the entry would leave the original vault unreachable, with nothing pointing at its data. Re-registering the same path is allowed, and is how an edit to a config file gets picked up (including fixing one that failed to open).forget_vaultfrees a name; it is registry bookkeeping only and never touches the vault's config file or the data in its origin.
Commands
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option — the same terms as the rest of the workspace.