explore

package
v0.35.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 6, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package explore is Explore data (spec/features/explore-data-handoff): the intent-first menu that hands database access to DataTug CLI or names DataTug.app's honest limitation, never running DataTug itself.

Choosing DataTug CLI checks whether `datatug` is on PATH, writes a four-key descriptor with no token under <OVDB home>/explore/datatug/, and renders the environment-variable lines, the token command and the exact `datatug query run` command for the caller's shell family (REQ:prepare-datatug-cli-connection). --no-policies is always in the printed command: spike S4 confirmed a fresh DataTug home has no access policies, so omitting it fails every newcomer's first run (accesspolicies.ErrNoPolicies). Every fact here was proven end to end in spike S4 before this package existed.

Index

Constants

View Source 
const (
	ActionDataTugCLI = "datatug_cli"
	ActionDataTugApp = "datatug_app"
)

Next actions a presentation offers in place (envelope.Next.Action).

View Source 
const AppURL = "https://datatug.app"

AppURL is DataTug.app's public URL (README.md: "Source code for DataTug.app (https://datatug.app)").

View Source 
const DefaultCollection = "lists"

DefaultCollection is the root collection Explore data suggests trying first: the demo's own top-level collection, and a reasonable guess for any other database (nested collections are not reachable — REQ table).

View Source 
const PrincipalID = "local-owner"

PrincipalID is the fixed, datatug-cli-local convention spike S4 confirmed: OVDB never validates it, only datatug-cli's own destination-binding check does (source.go's OpenSource and ExecuteQueryToRecordsReader).

View Source 
const TokenEnv = "OVDB_DATATUG_TOKEN"

TokenEnv is the descriptor's fixed tokenEnv value: datatug-cli derives "_BASE_URL" and "_PRINCIPAL_ID" from it (spike S4).

Variables

View Source 
var InstallCommands = []string{
	"brew tap datatug/tap && brew install datatug",
	"go install github.com/datatug/datatug-cli@latest",
}

InstallCommands are shown when datatug is not on PATH (REQ:prepare-datatug-cli-connection).

Functions

func ApplyOnPath 

func ApplyOnPath(document *DataTugCLI, onPath bool)

ApplyOnPath sets document's OnPath, InstallCommands and Next from onPath, the one place both Prepare (the server's own check) and a client overriding it with its own process's PATH (F2) compute them, so the two can never drift into different wording for the same boolean.

func CopyText 

func CopyText(document DataTugCLI) string

CopyText is what a copy action (TUI "c", web's copy button) puts on the clipboard for document: the environment variables and the query command, in the order they are printed — everything needed once the token placeholder is filled in, byte for byte what is shown (review-inc-7.md F4).

func DatabaseNotFound 

func DatabaseNotFound(db string) *envelope.Error

DatabaseNotFound is the shared not_found envelope for an unregistered database, so every caller (the server's own endpoint, the client's pure read) reports it the same way (review-inc-7.md F8: an unregistered database used to be a silent success in --json).

func DescriptorPath 

func DescriptorPath(home, db string) string

DescriptorPath is where db's descriptor lives under the OVDB home.

func IsDemo 

func IsDemo(home, db string, databases []setup.Database) bool

IsDemo reports whether db is the registered TODO demo among databases.

func OnPath 

func OnPath(lookPath LookPath) bool

OnPath reports whether datatug is on PATH, using lookPath (exec.LookPath when nil).

func QueryCommand 

func QueryCommand(goos, descriptorPath, collection string) string

QueryCommand is the exact `datatug query run` command for goos, with --no-policies always present: spike S4 proved a fresh DataTug home has no access policies, so a newcomer following the command without it always hits accesspolicies.ErrNoPolicies. The --db target is always quoted (spike S4's own text), unlike --from/--as, which stay bare for an ordinary value exactly as spike S4 shows and are quoted only when shellQuote must.

func ResolveCollection 

func ResolveCollection(isDemo bool, requested string, collections []string, db string) (string, *envelope.Error)

ResolveCollection picks the root collection to query (review-inc-7.md F5): the demo always defaults to DefaultCollection; any other database with exactly one root collection defaults to it; with several, or none registered, --collection is required and the error names the choices. A value containing "/" is refused: datatug-cli's --from builds a single root-collection reference (datatug-cli#256), so a path is silently sent as one literal collection name and always comes back empty, never an error — the exact trap spike S4 documented.

func ShellText 

func ShellText(goos string, lines []EnvLine) string

ShellText renders lines as goos's export syntax: POSIX `export NAME=value` (unquoted for the token placeholder, double-quoted otherwise) or PowerShell `$env:NAME = "value"` — the shell family of the OVDB process's own runtime.GOOS, with no other detection (plan simplification #12).

func TokenCommand 

func TokenCommand(goos, db string) string

TokenCommand is the command that mints the read-only token Explore data names but never mints or prints itself (REQ:prepare-datatug-cli-connection).

func WriteDescriptor 

func WriteDescriptor(path string, descriptor Descriptor) error

WriteDescriptor writes descriptor to path as an owner-only file, creating its owner-only parent directories.

Types

type DataTugApp 

type DataTugApp struct {
	Schema   int             `json:"schema"`
	Database string          `json:"database"`
	URL      string          `json:"url"`
	Next     []envelope.Next `json:"next"`
}

DataTugApp is the body of Choosing DataTug.app (REQ:honest-datatug-app-state): the honest limitation, Use DataTug CLI instead and Open DataTug.app — never a control implying OVDB can open a database there.

func NewDataTugApp 

func NewDataTugApp(db string) DataTugApp

NewDataTugApp builds the DataTug.app document for db.

type DataTugCLI 

type DataTugCLI struct {
	Schema          int             `json:"schema"`
	OnPath          bool            `json:"on_path"`
	Collection      string          `json:"collection"`
	DescriptorPath  string          `json:"descriptor_path"`
	Descriptor      Descriptor      `json:"descriptor"`
	EnvLines        []EnvLine       `json:"env_lines"`
	Shell           string          `json:"shell"`
	ShellText       string          `json:"shell_text"`
	TokenCommand    string          `json:"token_command"`
	QueryCommand    string          `json:"query_command"`
	InstallCommands []string        `json:"install_commands,omitempty"`
	Next            []envelope.Next `json:"next"`
}

DataTugCLI is the body of Choosing DataTug CLI: the four-key descriptor (written as a side effect, matching REQ:prepare-datatug-cli-connection), the environment-variable lines, the token command and the exact query command, plus install guidance when datatug is not found.

func Prepare 

func Prepare(lookPath LookPath, home, baseURL, db, collection string) (DataTugCLI, error)

Prepare builds and writes the DataTug CLI connection for db (capability row 22), on the server at baseURL, with collection (DefaultCollection when empty). lookPath checks the calling process's own PATH; a caller that instead wants the answer relayed by a different process (the local server, over HTTP) should pass nil and let ApplyOnPath override it — see review-inc-7.md F2: an agent's or shell's PATH commonly differs from whatever PATH started the detached OVDB server, so a check made inside the server is not the client's PATH and must never be presented as if it were.

type Descriptor 

type Descriptor struct {
	BaseURL     string `json:"baseUrl"`
	DatabaseID  string `json:"databaseId"`
	TokenEnv    string `json:"tokenEnv"`
	PrincipalID string `json:"principalId"`
}

Descriptor is exactly what datatug-cli's OpenSource accepts: any other key, including a token, is a hard error there, so this struct is the only place this shape may grow (spike S4).

func NewDescriptor 

func NewDescriptor(baseURL, db string) Descriptor

NewDescriptor builds the descriptor for db at baseURL (REQ:prepare-datatug-cli-connection).

type EnvLine 

type EnvLine struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

EnvLine is one exported/assigned environment variable, rendered for the caller's shell family.

func EnvLines 

func EnvLines(descriptor Descriptor, tokenCommand string) []EnvLine

EnvLines is the three environment variables datatug-cli reads, matching descriptor byte-for-byte (spike S4: baseUrl and principalId are compared as exact strings).

type LookPath 

type LookPath func(name string) (string, error)

LookPath resolves whether name is on PATH; exec.LookPath when nil. 

type Menu struct {
	Schema        int    `json:"schema"`
	Database      string `json:"database"`
	IsDemo        bool   `json:"is_demo"`
	DataTugCLIKey string `json:"datatug_cli_description_key"`
	DataTugAppKey string `json:"datatug_app_description_key"`
}

Menu is the intent-first choice (REQ:intent-first-menu): DataTug CLI and DataTug.app, each naming db and what works today, before any file is written. is Demo picks the demo-specific DataTug CLI copy (REQ:demo-copy-is-specific).

func NewMenu 

func NewMenu(db string, isDemo bool) Menu

NewMenu builds the menu for db; isDemo is whether db is the installed TODO demo (setup.FindDemo). Both description keys name real "what works today" copy, never the option's own label.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.