Documentation
¶
Overview ¶
The S1 half of local/remote validation parity.
Without it, `agentry validate` would run only the manifest V-rules and the S3/S4 content scan. That leaves a real gap: a committed .dylib, a vendored tarball, or a Latin-1 README passes locally and is rejected by the server's S1 inventory at submit — the "works on my machine, fails at publish" round-trip that parity exists to prevent.
This file closes that gap by running the same three S1 checks the pipeline runs, over the resolved include set, with the same severities:
S1/binary-executable critical content-sniffed ELF/Mach-O/PE/class S1/nested-archive critical content-sniffed zip/gzip/zstd/bzip2/xz/tar S1/non-utf8 low text file that is not valid UTF-8
Detection is by MAGIC BYTES, never by extension: renaming evil.so to notes.md is the first thing anyone tries, and the server is not fooled by it either.
The fourth S1-adjacent check, oversized files against the archive quotas — is deliberately NOT repeated here: manifest rule V8 already enforces MaxFiles/MaxFileBytes/MaxImageFileBytes/MaxArchiveBytes over the same resolved include set, in the same command, and reporting one oversized file twice would make the output worse rather than safer.
Parity is by construction: the detection predicates are pkg/archive's, the ones the server's S1 stage classifies with (below).
Package validate is `agentry validate`'s workspace check: offline parity with the server's submit validation — every manifest rule pkg/manifest reports (ManifestRules), the S1 inventory subset (localscan.go), and the S3/S4 scan via pkg/rules, run over the files publish would actually ship. It lives outside the command's main package so that the Drafter's post-step (pkg/drafter) checks a draft with the same code in every client: `agentry validate`, `agentry draft` and the desktop's draft on this computer write one report, the `validate --json` shape.
Index ¶
- Constants
- func Embedded() (*rules.Bundle, string, error)
- func ManifestRules() string
- func PrintStages(w io.Writer, r Report)
- func PrintUnfinished(w io.Writer, label string, us []Unfinished)
- func ReadManifest(dir string) (*manifest.Manifest, error)
- type Finding
- type InventoryFinding
- type Issue
- type Manifest
- type Options
- type Report
- type RulesLoader
- type Stages
- type Unfinished
Constants ¶
const PlaceholderNamespace = "your-namespace"
PlaceholderNamespace is the namespace a scaffold writes when it knows none. It passes the namespace grammar, so only this check catches it.
Variables ¶
This section is empty.
Functions ¶
func Embedded ¶
Embedded is the S4 bundle embedded in this binary, the floor every client validates under.
func ManifestRules ¶
func ManifestRules() string
ManifestRules names the manifest rules a validation runs, in the form the report and the command's help print them ("V1-V5, V7-V11"). It is read from pkg/manifest's own rule list, so a rule the core adds is named here without a change in this repository.
func PrintStages ¶ added in v0.7.35
PrintStages prints the report's closing block: the stages it ran here, the ones only the registry runs, and that the registry's verdict decides.
func PrintUnfinished ¶ added in v0.7.35
func PrintUnfinished(w io.Writer, label string, us []Unfinished)
PrintUnfinished prints the scaffold lines, one per line, labelled.
Types ¶
type Finding ¶
type Finding struct {
RuleID string `json:"ruleId"`
Scanner string `json:"scanner"`
Severity string `json:"severity"`
Confidence string `json:"confidence"`
Title string `json:"title"`
FilePath string `json:"filePath"`
LineStart int `json:"lineStart,omitempty"`
LineEnd int `json:"lineEnd,omitempty"`
Excerpt string `json:"excerpt,omitempty"`
Detail map[string]string `json:"detail,omitempty"`
}
Finding is one S3/S4 scanner hit.
type InventoryFinding ¶
type InventoryFinding struct {
Scanner string `json:"scanner"`
Severity string `json:"severity"`
Title string `json:"title"`
FilePath string `json:"filePath"`
Detail string `json:"detail,omitempty"`
}
InventoryFinding is one S1-subset result.
type Issue ¶
type Issue struct {
Rule string `json:"rule"`
Severity string `json:"severity"`
Path string `json:"path,omitempty"`
Message string `json:"message"`
}
Issue is one manifest rule's result.
type Manifest ¶
type Manifest struct {
Namespace string `json:"namespace"`
Name string `json:"name"`
Version string `json:"version"`
SchemaVersion int `json:"schemaVersion"`
Modes []string `json:"modes"`
}
Manifest is the report's header: what agent.yaml said about itself.
type Options ¶
type Options struct {
// Strict treats manifest warnings as errors.
Strict bool
// Out is the narration, ErrOut its notes; nil discards them.
Out, ErrOut io.Writer
// Rules loads the S4 signature bundle and says where it came from; nil
// is the bundle embedded in this binary (Embedded). A loader that fails
// fails the check: it never passes content S4 did not examine.
Rules RulesLoader
// RefuseUnfinished fails the check on a scaffold line the package still
// ships (a TODO, a placeholder namespace, author or licence, a
// scaffold's README). `agentry validate` sets it; a draft's post-step
// does not, since a fresh draft carries the Drafter's own README line
// and licence note until its author has read it.
RefuseUnfinished bool
}
Options are how a workspace is checked.
type Report ¶
type Report struct {
Passed bool `json:"passed"`
// Manifest is what agent.yaml said about itself.
Manifest Manifest `json:"manifest"`
// Issues are the manifest rules' results, errors and warnings.
Issues []Issue `json:"issues"`
// Inventory is the S1 subset over the resolved include set.
Inventory []InventoryFinding `json:"inventory"`
// Findings are the S3/S4 scanner hits.
Findings []Finding `json:"findings"`
// ReadErrors are include-set files that could not be read.
ReadErrors []string `json:"readErrors"`
// Unfinished are scaffold lines the package still ships. They fail the
// report only when the check was asked to refuse them
// (Options.RefuseUnfinished); a draft's report lists them either way.
Unfinished []Unfinished `json:"unfinished"`
// Stages names the registry's stages this check ran here and the ones
// only the registry runs, so a pass is never read as more than it is.
Stages Stages `json:"stages"`
FileCount int `json:"fileCount"`
Bundle struct {
Version string `json:"version"`
Source string `json:"source"`
} `json:"bundle"`
Counts struct {
Errors int `json:"errors"`
Warnings int `json:"warnings"`
InventoryFailing int `json:"inventoryFailing"`
Findings int `json:"findings"`
Unfinished int `json:"unfinished"`
} `json:"counts"`
Strict bool `json:"strict"`
// RefuseUnfinished says whether Unfinished counted against Passed.
RefuseUnfinished bool `json:"refuseUnfinished"`
}
Report is the `validate --json` shape: the rules and scan findings as data, and the verdict `publish` would reach. A draft's draft.json carries it as its validation.
type RulesLoader ¶
RulesLoader loads the S4 signature bundle and says where it came from.
type Stages ¶ added in v0.7.35
Stages are the registry's checks by name: those a validation ran on this computer, and those the registry runs only when the version is submitted.
type Unfinished ¶ added in v0.7.35
type Unfinished struct {
// File is the shipped file, relative to the package.
File string `json:"file"`
// Line is the 1-based line, absent for a manifest field.
Line int `json:"line,omitempty"`
// Marker names what was found, e.g. "TODO summary".
Marker string `json:"marker"`
// Message says what to do about it.
Message string `json:"message"`
}
Unfinished is a line a scaffold wrote for the author to replace, still in a file the package ships: the QuickAgent template's, `agentry init`'s or the Drafter's. The registry would publish it as it stands, so `agentry validate` and `agentry publish` refuse it.
func UnfinishedIn ¶ added in v0.7.35
func UnfinishedIn(dir string) ([]Unfinished, error)
UnfinishedIn lists the scaffold lines the package in dir would ship, read from the files publish.include resolves to. `agentry publish` refuses an upload while it lists any. An error is a package it could not read.