README
¶
xoluman
A web-based operator UI for xolu: manage instances, browse and edit data, run queries, and move data in and out.
What xoluman is
xoluman is a single Go binary, server-rendered with
minty and htmx — no hand-written HTML,
no React. It talks to one or more xolu
instances (local or remote) through xolu's own Go client library
(github.com/ha1tch/xolu/pkg/client), and adds what a single xolu
instance doesn't provide for itself.
xoluman does not duplicate xolu's data model or query engines — it is a thin, generic operator surface over whatever xolu instance is active.
What's built
- Connections — a registry of named xolu instances, each with its own base URL, auth mode, token, and default tenant. Test a connection's reachability before saving it, not just after. Switch between instances without restarting.
- Entity browser and editor — every entity type with actual data shows up, schema-registered or not (xolu doesn't require a schema; discovery and editing both work either way, inferring fields from real data when there's no schema to read them from). REF fields render as clickable, resolved-label links, not raw IDs. Bulk import from CSV or JSON. A Tabulator-based grid view for editing many rows at once.
- Schema promotion — preview a heuristic-inferred schema for a schemaless entity type, then promote it: strict (validates every existing row first, atomic, rejection is a normal outcome with the exact failures shown) or flex (fast, with the trade-off — existing rows not migrated — stated plainly, not buried).
- Blob browser — xolu's blob store presented as a navigable folder
hierarchy (a xoluman-only convention over xolu's flat key space,
since xolu keys can't contain
/). Upload, download, delete, and create real empty folders that persist even with nothing in them. - Query editor — OQL, Sulpher, and raw REST requests against the active connection, each with real CodeMirror 6 syntax highlighting, not a plain textarea.
- Dark/light theme, persisted, following system preference by default.
Status
Actively developed. See docs/TRACKING.md for the live register of open work, docs/KNOWN_ISSUES.md for intentional limits and real gotchas found along the way (several in xolu itself, not just xoluman), and CHANGELOG.md for what's actually shipped, release by release.
Not yet built: a backup/export UI (the xolu client method exists; the xoluman-side feature doesn't yet), and an FSM definition editor (being worked on separately).
Relationship to xolu and Seam AMS
xoluman depends on github.com/ha1tch/xolu/pkg/client for all
communication with xolu instances — it adds no parallel HTTP layer of
its own. Several client-library gaps found while building xoluman
(blob methods, an async tenant-scoped export, a raw request escape
hatch for the query editor's REST mode, schema registration, and two
bonus items — ListEntities and schema promotion) were filed as
requests and delivered upstream in xolu itself, not built as
workarounds inside xoluman.
xoluman's UI conventions (minty, htmx, server-rendered layout and components) follow the same practice established in Seam AMS, trimmed to what a generic operator tool needs: no tenant-specific business modules, no asset domain model, no tabs/visibility-rule form engine — just flat, schema-driven forms over arbitrary entity types, with a graceful fallback when there's no schema at all.
Development workflow
Tooling mirrors xolu's: repoman (repoman/) for editing, the work
register, and dormant-guard tracking; a Makefile for build/test;
tracking documents under docs/ following the same taxonomy
(CHANGELOG.md, docs/TRACKING.md, docs/RESOLVED.md,
docs/KNOWN_ISSUES.md).
make build # → ./xoluman
make test # go test ./...
make test-race # go test ./... -race
make coverage # coverage profile + summary
make css # regenerate web/static/css/tailwind.css after adding
# or removing Tailwind classes in Go source (npm install
# once first; requires Node.js — build-time only, never
# at runtime, see docs/KNOWN_ISSUES.md)
All third-party frontend assets (htmx, Tabulator, Lit, CodeMirror) are
vendored under web/static/vendor/ and embedded via go:embed — the
built binary needs no network access to serve its own UI. See
web/static/vendor/VENDOR.md for exact
versions, licenses, and re-vendoring instructions.
License
Copyright (c) 2026 haitch
Apache 2.0 — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
xoluman
command
Command xoluman is a web-based operator UI for xolu — connection management, data browsing/editing, query running, and blob access, against one or more local or remote xolu instances.
|
Command xoluman is a web-based operator UI for xolu — connection management, data browsing/editing, query running, and blob access, against one or more local or remote xolu instances. |
|
internal
|
|
|
blobfs
Package blobfs presents xolu's flat blob key store as a navigable folder hierarchy — a xoluman-only presentation convention, not anything xolu itself is aware of.
|
Package blobfs presents xolu's flat blob key store as a navigable folder hierarchy — a xoluman-only presentation convention, not anything xolu itself is aware of. |
|
config
Package config resolves xoluman's on-disk configuration directory and reads/writes its app-level settings.json — currently just the secret storage backend selection (file vs keyring), made once at first run per docs/KNOWN_ISSUES.md's recorded decision.
|
Package config resolves xoluman's on-disk configuration directory and reads/writes its app-level settings.json — currently just the secret storage backend selection (file vs keyring), made once at first run per docs/KNOWN_ISSUES.md's recorded decision. |
|
connstore
Package connstore manages xoluman's registry of named xolu instance connections — local and remote, each with its own base URL, auth mode, token, and optional default tenant.
|
Package connstore manages xoluman's registry of named xolu instance connections — local and remote, each with its own base URL, auth mode, token, and optional default tenant. |
|
fieldmeta
Package fieldmeta implements listbox/select field configuration as xoluman-owned bookkeeping documents inside the target xolu instance — the same pattern already established for T-09's blob-folder entities: a plain entity type (xoluman_field_meta), created schema-lessly (confirmed: xolu accepts writes to an unregistered entity type — "if no schema is registered, all writes pass"), not a new xolu primitive.
|
Package fieldmeta implements listbox/select field configuration as xoluman-owned bookkeeping documents inside the target xolu instance — the same pattern already established for T-09's blob-folder entities: a plain entity type (xoluman_field_meta), created schema-lessly (confirmed: xolu accepts writes to an unregistered entity type — "if no schema is registered, all writes pass"), not a new xolu primitive. |
|
formengine
Package formengine renders a flat, schema-driven form from xolu's own JSON Schema field extraction (client.FieldDef), for arbitrary entity types on arbitrary xolu instances.
|
Package formengine renders a flat, schema-driven form from xolu's own JSON Schema field extraction (client.FieldDef), for arbitrary entity types on arbitrary xolu instances. |
|
importer
Package importer parses uploaded CSV/JSON files into rows ready to create as entities, against a target entity type's schema.
|
Package importer parses uploaded CSV/JSON files into rows ready to create as entities, against a target entity type's schema. |
|
modules
Package modules is xoluman's module registry: self-registering feature areas, with both the top nav and the route table built from whatever's registered rather than hand-listed per page or wired centrally in internal/server/server.go.
|
Package modules is xoluman's module registry: self-registering feature areas, with both the top nav and the route table built from whatever's registered rather than hand-listed per page or wired centrally in internal/server/server.go. |
|
oqlclassify
Package oqlclassify determines whether an OQL query's result rows are, one-to-one, complete and unmodified documents of a single real entity type — the one case where routing the result into xoluman's existing, live-editable entity grid is genuinely safe.
|
Package oqlclassify determines whether an OQL query's result rows are, one-to-one, complete and unmodified documents of a single real entity type — the one case where routing the result into xoluman's existing, live-editable entity grid is genuinely safe. |
|
seedapply
Package seedapply executes a loaded seed (internal/seeds) against a real, connected xolu tenant.
|
Package seedapply executes a loaded seed (internal/seeds) against a real, connected xolu tenant. |
|
seeds
Package seeds defines xoluman's seed package format — a directory carrying a manifest (this file), schemas, data, and other xolu primitive definitions that can be previewed and applied to a connected tenant in one action.
|
Package seeds defines xoluman's seed package format — a directory carrying a manifest (this file), schemas, data, and other xolu primitive definitions that can be previewed and applied to a connected tenant in one action. |
|
seedsremote
Package seedsremote fetches the opt-in remote seed source (ha1tch/xoluseeds) into a local cache directory, from which it's then discoverable through exactly the same internal/seeds.Discover path as any local seed — no separate "remote seed" data model exists anywhere else in xoluman.
|
Package seedsremote fetches the opt-in remote seed source (ha1tch/xoluseeds) into a local cache directory, from which it's then discoverable through exactly the same internal/seeds.Discover path as any local seed — no separate "remote seed" data model exists anywhere else in xoluman. |
|
server
Package server wires xoluman's HTTP routes to their handlers.
|
Package server wires xoluman's HTTP routes to their handlers. |
|
ui
dxp.go implements T-25's design (docs/proposals/dxp-transactions.md): a def picker plus a dynamically-generated binding-fill form, deliberately its own view rather than a fourth query-editor mode — a DXP transaction has no query language, only a chosen definition and the parameter values its participants reference.
|
dxp.go implements T-25's design (docs/proposals/dxp-transactions.md): a def picker plus a dynamically-generated binding-fill form, deliberately its own view rather than a fourth query-editor mode — a DXP transaction has no query language, only a chosen definition and the parameter values its participants reference. |
|
xoluext
Package xoluext bridges xoluman's own types onto xolu's Go client (github.com/ha1tch/xolu/pkg/client).
|
Package xoluext bridges xoluman's own types onto xolu's Go client (github.com/ha1tch/xolu/pkg/client). |
|
Package web embeds xoluman's static assets (currently just the vendored modal controller) into the binary, matching the same go:embed pattern Seam AMS uses for its own web package — a single deployable binary with no dependency on files existing relative to the working directory.
|
Package web embeds xoluman's static assets (currently just the vendored modal controller) into the binary, matching the same go:embed pattern Seam AMS uses for its own web package — a single deployable binary with no dependency on files existing relative to the working directory. |