Components declare the programs Link runs
A component is a program lnk installs and runs on its own: a plugin,
a harness adapter, a connection, a tool, a store driver or a standalone
program. link-component is the one typed description of a component
that its build, the installed program and lnk all share.
What a component is
A component is one Cargo package with one program, lnk-<id>, and a
plugin.toml beside it. Its kind says which interface it answers:
plugin, harness, connection, tool, store or program. A
library or a contract isn't a component, since programs link it and
nothing installs it.
Where its description comes from
Cargo gives a component its identity: its id, Cargo name, version,
license, description and program, the Component type. Its
plugin.toml gives its kind, what it requires and recommends, its
place in lnk up's menu, how it's removed, and its documentation, read
into Source. Its actions.toml gives its actions, each an Action
keyed by its command line: its help, its arguments, whether it's
hidden, plumbing between programs a person never runs, and where it's
offered (Surface), on the CLI, as an agent's command, a route or a
tool. A field either type doesn't know is refused.
What a hidden command is
A hidden command, or a command under a hidden group, is Link's and not a
person's. Link runs it, such as a backend's typed request on standard
input, and never offers it. The registry carries it as Command.hidden,
so lnk --help does not list its group and Next's graph does not count
it. Routing still dispatches it.
What each command leads to
An action's next and fail are the Nexts its command can give on
success and on failure, each a command as cmd! writes it (lnk agent connect <connection>), retry for itself again: Next's graph, read by
format's check.
What each command diagnoses
An action's diagnoses is the kind of name (agent, box) its command
diagnoses: given one, <command> <name> --json answers that name's
state as typed blocks, the same a person sees, and lnk issue puts it
in an issue scrubbed. Each kind has one; an end-to-end test holds the
contract, with the kinds no command diagnoses yet on a list that may
shrink, never grow.
What an installed program answers
At build, link-component-build joins the two into Resolved, the
self-contained answer embedded in the program. When lnk asks a
program what it is, this is what it gets back, so help, routing and the
install menu work without installing anything the program needs.
What an operation needs
requirements works out what one command needs installed, from the
requires of every component it reaches: a plugin it runs, with the
command and options it runs it with, or a capability of the machine.
The machine's OS, architecture and libc, and the operation's options,
decide which apply. A recommendation installs nothing until it's
chosen, and a cycle of required commands is refused.
Options from another file
A command can take its options from another file with
options_ref = { file, pointer }. Options written beside it only add
values the operation's owner derives from them.
Documentation
A component's [documentation] names its topic, where lnk man and
the website find its pages, and says with quickstart = false that its
first page has no quickstart, for a program only Link runs. An
installed plugin carries its own pages, and one that isn't installed
shows where to get it.
What a release ships
Every member ships in a release unless its Cargo.toml holds it back
with released = false under [package.metadata.link]. A held member
stays in the code and is built and tested, and dev, QA and source
builds keep it. Only a release's registry, archives and website leave
it out. Any other value of released, true among them, is refused.
The registry of a release
A release's lnk is built with LNK_BUILD=release, and
link_component_build::registry then embeds only the released
components (link_component::release::registry). A released one's
recommendations of a held one are dropped, but a requirement of one,
or an upgrade that adds one, fails the build.
Its other parts
scripts/release/components.sh packages and seals the same selection,
and the website leaves out each folder scripts/documentation-index.json
marks "released": false. A repository check refuses a normal or build
dependency of a released crate on a held one, and holds the index's
marks to the crates'.
Account setup
account_services names exact HTTPS origins whose successful sign-in
sets up this component and its required plugins. Only declarations
embedded in the trusted core registry select components. A service
cannot supply a program, download URL or capability. A component with
account setup declares the questions it answers in answers; discovery
then reads the cached login through that existing typed question.
Action routes
An action offered as a route or tool names its callers and bridge,
exactly one of answer and carries, and positive limits.bytes and
limits.time_ms. The registry refuses incomplete definitions.
Caller discovery
The bridge establishes owner, agent, program or trigger from its
trusted context. Registry discovery filters actions by caller and surface;
request arguments cannot change the caller. Canonical routes use
/_link/<namespace>/<action>; encoded and relative paths do not match.
Answer budgets
A bridge applies each action's byte and time budgets before returning a
typed answer. streams distinguishes a stream from a single answer;
carries names a protocol relayed without a Link answer type.