README
¶
Global OpenCode JS plugin placement
Plan(Input) is a pure Go helper for one global local .js plugin. The caller
passes the intended filename, desired bundle SHA256, trusted owned preimage
SHA256 (if any), and its current observation of the target path. It returns the
selected root, plugins/<filename> target, a copied observation, and one of
create, replace, unchanged, or conflict. Conflict reasons distinguish a
foreign regular file, an edited owned file, and a non-regular object.
Root precedence is Override (the OpenCode config root itself), then
XDGConfigHome/opencode, then HomeDir/.config/opencode. An unset value is an
empty string. A selected root must be an absolute, clean path; invalid selected
values fail instead of choosing another root. FileName must be a single,
visible .js basename; separators, control characters, and traversal are
rejected. An observation whose path differs from the computed target is rejected.
Paths use the host Go
platform's filepath rules; this package makes no cross-platform loader claim.
The helper performs lexical containment only. It never reads the filesystem,
resolves symlinks, writes or removes files, changes package.json, or invokes
the legacy installer. The product transaction must verify the selected root
and plugins ancestors against symlink escapes, capture the target with a
no-follow observation, and compare the preimage again at commit time. It must
also own consent, registration, rollback, and recovery. An ownership digest is
meaningful only when read from the product's trusted ownership record; matching
bytes alone do not grant ownership. Changing the selected root requires an
explicit migration/reinstall decision by the product; this plan does not infer
or remove files at an old root.
Documentation
¶
Overview ¶
Package opencodeplugin plans placement of one global OpenCode local JS plugin. It has no filesystem or process effects. The caller owns observation and the compare-and-swap transaction that applies or removes the planned file.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ConflictReason ¶
type ConflictReason string
const ( ForeignFile ConflictReason = "foreign_file" ChangedFile ConflictReason = "changed_file" WrongKind ConflictReason = "wrong_kind" )
type Existing ¶
Existing is the caller's snapshot of the target. Nil means it was absent. Path must be the exact path returned by this planner, and SHA256 is required for a regular file.
type FileKind ¶
type FileKind string
FileKind describes the object at the target path, observed without following its final symlink. A regular file's SHA256 is the lowercase hex digest of its bytes. A symlink or other object is always a conflict.
type Input ¶
type Input struct {
HomeDir string
XDGConfigHome string
Override string
FileName string
DesiredSHA256 string
OwnedSHA256 string
Existing *Existing
}
Input supplies explicit environment values; Plan never reads process env. Override is the OpenCode config root itself. XDGConfigHome is its parent. OwnedSHA256 is the digest from the product's trusted ownership record; empty means no ownership claim. DesiredSHA256 is the proposed JS bundle's digest.
type Placement ¶
type Placement struct {
Root string
Target string
DesiredSHA256 string
Existing *Existing
Action Action
ConflictReason ConflictReason
}
Placement is a snapshot-based proposal, never authority to mutate the host. Existing is copied into the result so the caller can compare it again during its transaction. ConflictReason is nonempty only for Action == Conflict.
Source Files