Documentation
¶
Index ¶
- Constants
- Variables
- func CmdAlias(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdAwk(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdBase64(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdBasename(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdBracket(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdCat(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdCd(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdClear(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdColumn(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdComm(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdCommand(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdCut(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdDate(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdDiff(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdDirname(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdDu(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdEcho(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdEnv(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdEval(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdExpand(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdExport(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdExpr(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdFalse(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdFind(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdFold(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdGrep(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdHead(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdHelp(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdHistory(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdHostname(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdJoin(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdJq(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdLore(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdLs(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdMd5sum(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdMkdir(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdMv(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdNl(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdPaste(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdPatch(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdPrintenv(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdPrintf(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdPublish(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdRead(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdRev(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdRm(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdSed(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdSeq(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdSet(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdSha1sum(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdSha256sum(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdSkills(ctx CmdContext, args []string, w, errW io.Writer, stdin io.Reader) int
- func CmdSleep(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdSort(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdSource(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdSpawn(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdStat(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdTac(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdTail(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdTee(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdTest(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdTime(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdTimeout(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdTr(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdTree(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdTrue(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdType(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdUnalias(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdUnexpand(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdUniq(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdUnset(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdVersion(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdWc(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdWhich(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdWhoami(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func CmdXargs(ctx CmdContext, args []string, w io.Writer, errW io.Writer, stdin io.Reader) int
- func IsKnown(name string) bool
- func PrintLong(w io.Writer, f *vfs.FileInfo)
- func ReadInputLines(ctx CmdContext, files []string, stdin io.Reader, errW io.Writer, ...) ([]string, int)
- func Register(name string, fn CmdFunc)
- func RegisterAction(name string, a Action)
- func RegisterLoreSub(sub LoreSub)
- func RegisterSkill(name, description, content string)
- func WriteFile(ctx CmdContext, p string, data []byte, appendMode bool) (string, error)
- func WriteFileCAS(ctx CmdContext, p string, data []byte, base []byte) (string, error)
- func WriteFileCASMsg(ctx CmdContext, errW io.Writer, cmdName, p string, data []byte, base []byte) int
- func WriteFileMsg(ctx CmdContext, errW io.Writer, cmdName, p string, data []byte, ...) int
- type Action
- type CmdContext
- type CmdFunc
- type DocsetInfo
- type JobBackend
- type JobSpec
- type LoreSub
- type PublishTarget
- type SkillEntry
Constants ¶
const SkillsMarker = "user.lore.plugins.openlore.skills.v1"
Variables ¶
var PublishBaseURL string
PublishBaseURL is the base URL prefixed to a published path in the command's success output. Populated by the server at startup.
var Registry = map[string]CmdFunc{}
Registry maps command names to their implementations.
var Skills []SkillEntry
var VersionString = "unknown"
VersionString is set by the server at init time.
Functions ¶
func CmdBasename ¶
func CmdBracket ¶
func CmdCommand ¶
func CmdDirname ¶
func CmdHistory ¶
func CmdHostname ¶
func CmdLore ¶
CmdLore is the `lore` introspection dispatcher. Bare `lore` prints usage and exits 0; an unknown subcommand errors to stderr and exits 1. Subcommands are resolved from the loreSubs registry.
func CmdMkdir ¶
CmdMkdir creates directories. With -p it also creates missing parents and does not treat an existing directory as an error. A folder can only be created strictly inside a docset — you cannot create a docset (or its root) this way.
Usage: mkdir [-p] <dir>...
func CmdMv ¶ added in v0.3.0
CmdMv moves a file through the same atomic write and delete seams as the other mutating commands. Directory moves are deliberately unsupported: the VFS has no atomic tree-write operation, so emulating one would expose a partially copied tree when a write is denied or held for approval.
Usage: mv <source> <destination>
func CmdPatch ¶
CmdPatch applies a unified diff (read from stdin) to a target file and commits the result as a single atomic whole-object write. The patch's own context/removed lines are the precondition: if the file has drifted from the diff's base, the hunk fails to apply and patch reports a conflict (exit 1), committing nothing — exactly like git applying onto a stale base.
Usage: patch <file> < changes.diff
func CmdPrintenv ¶
func CmdPublish ¶
CmdPublish writes stdin to a file inside a publish inbox. The commit goes through the session filesystem (`WriteFile`), so it inherits the same per-identity write scoping, atomic CAS, and approval gating as every other write verb — there is no longer a separate direct-to-disk path. The session's publish inboxes come from the host via CmdContext.PublishTargets and are used here only for the usage listing and per-docset size cap; the filesystem is the authority on whether the write is actually permitted.
func CmdRm ¶
CmdRm removes files and, with -r, directory trees. A directory requires -r. Deletion of a gated path (or a tree containing one) does not happen immediately: it becomes a pending delete changeset that an approver must resolve, reported here as pending (not a failure). -f only suppresses not-found / missing-operand errors; it never bypasses approval.
Multiple operands are independent: one failing does not stop the others, but the command exits non-zero if any failed.
Usage: rm [-r] [-f] <path>...
func CmdSha1sum ¶
func CmdSha256sum ¶
func CmdSkills ¶
CmdSkills prints agent-facing usage with no arguments while management commands emit records exclusively.
func CmdSpawn ¶
CmdSpawn runs an external command asynchronously and writes its stdout back into the lore once it finishes — without blocking the caller.
spawn --writes <path> [--append] -- <command...>
The target must sit within the session's writable scope; spawn fails fast at submit time otherwise. The command runs as the OpenLore service user, so the verb is gated by ActionSpawn (operator-trusted identities only).
func CmdTee ¶
CmdTee reads stdin fully, writes it to stdout, and commits it to each file argument as a single atomic whole-object write (no streaming). `-a` appends. On a read-only filesystem the file writes fail with a clear error, but the pass-through to stdout still happens (so `tee` in a read-only pipe is inert for files but transparent for data).
func CmdTimeout ¶
func CmdUnalias ¶
func CmdUnexpand ¶
func CmdVersion ¶
CmdVersion prints the OpenLore version.
func ReadInputLines ¶
func ReadInputLines(ctx CmdContext, files []string, stdin io.Reader, errW io.Writer, cmdName string) ([]string, int)
ReadInputLines reads lines from files or stdin, used by many text commands.
func RegisterAction ¶
RegisterAction tags a command with a capability class. Host applications that register custom commands (e.g. knowledge-backend's `kb` and `lore-*`) use this so the gating layer classifies them correctly.
func RegisterLoreSub ¶ added in v0.3.0
func RegisterLoreSub(sub LoreSub)
RegisterLoreSub adds (or replaces) a core `lore` subcommand.
func RegisterSkill ¶
func RegisterSkill(name, description, content string)
func WriteFile ¶
WriteFile commits data to path through the writable filesystem as a single atomic whole-object operation. It is the one write seam shared by every blind write verb (`>`, `>>`, tee, publish): there is no streaming.
When appendMode is false it performs a whole-file overwrite governed by the session's write-conflict policy (see overwritePreconditions): under "hash" (the default) it is a compare-and-swap against the session's last-read hash for the path (or, if none was tracked, the content read at command time), so a concurrent change since the caller last saw the file surfaces a vfs.PreconditionError; under "last_write_wins" it is an unconditional atomic overwrite. When appendMode is true it runs a read-modify-write CAS loop so concurrent appends never clobber each other, regardless of policy.
A read-modify-write verb that already holds the base it transformed (sed -i) should call WriteFileCAS instead, so the precondition is the true base rather than a re-read.
It returns vfs.ErrReadOnly when the filesystem is read-only (the hard error surfaced to the agent), so callers can detect and message it.
func WriteFileCAS ¶
WriteFileCAS commits a whole-file overwrite where the caller already holds the base content it transformed (a read-modify-write verb such as sed -i). Under "hash" policy the write is a true compare-and-swap against base, so a concurrent change since base was read surfaces a vfs.PreconditionError rather than silently clobbering it; under "last_write_wins" it is unconditional.
func WriteFileCASMsg ¶
func WriteFileCASMsg(ctx CmdContext, errW io.Writer, cmdName, p string, data []byte, base []byte) int
WriteFileCASMsg is WriteFileMsg for the compare-and-swap (known-base) seam.
func WriteFileMsg ¶
func WriteFileMsg(ctx CmdContext, errW io.Writer, cmdName, p string, data []byte, appendMode bool) int
WriteFileMsg writes data and emits a uniform error line to errW on failure, returning a shell-style exit code (0 ok, 1 error). It centralizes the read-only, precondition, and generic error messaging for the write verbs.
Types ¶
type Action ¶
type Action string
Action classifies what a command does, for per-session capability gating.
const ( // ActionRead is any non-mutating command (ls, cat, grep, …). Default. ActionRead Action = "read" // ActionWrite mutates docset content (write, patch, tee, `>`/`>>`, sed -i). ActionWrite Action = "write" // ActionPublish publishes new sources (publish, kb publish). ActionPublish Action = "publish" // ActionSpawn runs external commands asynchronously and writes their output // back into the lore (spawn). It is powerful — the command runs as the // OpenLore service user — so it is granted only to identities the operator // has explicitly trusted (capability "spawn"), never to anonymous sessions. ActionSpawn Action = "spawn" // ActionAdmin reconfigures the server (lore-* mutations, config writes). ActionAdmin Action = "admin" )
func ActionFor ¶
ActionFor returns the capability class for a command name. Unclassified commands are ActionRead.
func InvocationAction ¶
InvocationAction returns the effective capability class for a specific invocation (name + args). It is ActionFor(name) except where a flag turns an otherwise read-only command into a mutation — notably `sed -i`, which edits in place and is therefore a write.
type CmdContext ¶
type CmdContext interface {
FS() vfs.FileSystem
Cwd() string
SetCwd(dir string)
Resolve(path string) string
GetEnv(key string) string
SetEnv(key, value string)
DeleteEnv(key string)
AllEnv() map[string]string
Exec(cmdLine string, w io.Writer, errW io.Writer, stdin io.Reader) int
ExecPipeline(line string, w io.Writer, errW io.Writer, stdin io.Reader) int
// ActionAllowed reports whether the session may perform the given
// capability class. A command that introspects the available surface
// (e.g. help) uses this to hide actions the session is not allowed to use.
ActionAllowed(a Action) bool
// WriteConflictPolicy reports the policy governing whole-file overwrites to
// the given resolved path. Defaults to vfs.PolicyHash (compare-and-swap)
// when the host has not configured a resolver.
WriteConflictPolicy(resolvedPath string) vfs.WriteConflictPolicy
// Docsets reports the docsets this session can access, with their display
// paths, direct writability, and attributes. Used by `lore docsets`. The
// host (server) computes this once per session; a standalone shell returns
// nil.
Docsets() []DocsetInfo
// PublishTargets reports the publish inboxes this session may publish to,
// with their per-docset size caps. Used by `publish`. The host computes this
// once per session; a standalone shell returns nil.
PublishTargets() []PublishTarget
// MetaExtenders reports the plugin-contributed extenders that enrich `lore
// meta` records. The host installs these once per session; a standalone
// shell returns nil.
MetaExtenders() []meta.Extender
MetaFilters() []meta.Filter
// Validators reports plugin-contributed checks used by `lore validate`.
Validators() []validation.Validator
SkillsManagementEnabled() bool
SkillsRemoteTimeout() time.Duration
SkillsRemoteMaxBytes() int64
}
CmdContext provides the interface that commands use to interact with the shell. Implemented by shell.Shell.
type DocsetInfo ¶
type DocsetInfo struct {
// Name is the docset's logical name (its key in the auth config).
Name string
// Paths contains the single display path represented by this row. It remains
// a slice so existing command consumers can parse canonical rows unchanged.
Paths []string
// AliasTarget is the canonical display path when this row represents an
// alias. Empty means the row is canonical.
AliasTarget string
// Grant is retained for standalone callers that provide one grant directly.
Grant string
// Grants are the effective grants contributed by the session's roles.
Grants []string
// Writable reports whether this session may write to the docset directly
// with the normal write verbs. This is the FS-authoritative answer.
Writable bool
// Home reports whether this docset is the session's home docset ($HOME).
Home bool
// Inbox reports whether the docset declares an inbox folder (used by the
// publish grant). It says nothing about the inbox path or size — that lives
// in PublishTarget.
Inbox bool
AgentSkills bool
}
DocsetInfo describes one docset a session can access. It is the per-session view surfaced by `lore docsets` — the host resolves it from the session's role-policy snapshot.
type JobBackend ¶
JobBackend schedules and runs JobSpecs. The server supplies the implementation (it owns the bounded worker pool + the in-memory registry). Submit returns the job id immediately; the work runs in the background.
var Jobs JobBackend
Jobs is the active job backend, set by the server at startup. Nil when the server has no job manager (e.g. an embedded read-only server).
type JobSpec ¶
type JobSpec struct {
Command string
Target string
Append bool
Identity string
WriteCtx CmdContext
}
JobSpec describes one asynchronous external job: run Command via a shell, then commit its stdout to Target through WriteCtx (a frozen, session-detached write context). Append selects `>` vs `>>` semantics. Identity is for provenance.
type LoreSub ¶ added in v0.3.0
type LoreSub struct {
// Name is the subcommand word, e.g. "meta" in `lore meta`.
Name string
// Summary is the one-line description shown in `lore` usage.
Summary string
// Run executes the subcommand. args are the tokens after the subcommand
// name (so `lore meta backend` calls Run with ["backend"]).
Run CmdFunc
}
LoreSub is a registered core `lore` subcommand.
type PublishTarget ¶
PublishTarget is a writable inbox: its logical docset name (the first path segment used in `publish /<name>/<file>`), the resolved virtual filesystem path of the docset's inbox that a publish is routed into, and the per-docset size cap. A `publish /<name>/<rest>` writes to InboxPath/<rest>, not to the docset root — the inbox is the only place the publish grant may create files.
type SkillEntry ¶
type SkillEntry struct{ Name, Description, Content string }
Source Files
¶
- actions.go
- awk.go
- base64_cmd.go
- basename.go
- cat.go
- cd.go
- checksum.go
- column.go
- comm.go
- context.go
- cut.go
- date.go
- diff.go
- du.go
- echo.go
- env.go
- expand.go
- export.go
- expr.go
- find.go
- fold.go
- grep.go
- head.go
- help.go
- helpers.go
- history.go
- join.go
- jq.go
- lore.go
- lore_meta.go
- lore_validate.go
- ls.go
- misc.go
- mkdir.go
- mv.go
- nl.go
- paste.go
- patch.go
- printf.go
- publish.go
- read_cmd.go
- registry.go
- rev.go
- rm.go
- sed.go
- seq.go
- skills.go
- sort_cmd.go
- source.go
- spawn.go
- stat.go
- tac.go
- tail.go
- tee.go
- test_cmd.go
- tr.go
- tree.go
- type_cmd.go
- uniq.go
- version.go
- wc.go
- which.go
- whoami.go
- write.go
- xargs.go