Help us shape the future of Go! Take the 2026 Go Developer Survey

hostsurface

package
v1.1.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DeclaredHookTimings 

func DeclaredHookTimings(fsys fs.FS, loop string) ([]string, error)

DeclaredHookTimings returns the lifecycle timings the loop's intents declare, in canonical order. A loop without an intents file is a hook-less loop (nil, nil) — legitimate, not an error; a present-but-invalid intents file fails closed.

func EmbeddedHookUniverse 

func EmbeddedHookUniverse() (hosts, loops []string, err error)

EmbeddedHookUniverse discovers the (hosts, loops-with-intents) coverage universe from the embedded assets — derived, not hardcoded, so a future loop or host that ships hook data is admitted to every gate (loop validate, golden pins) without editing a literal.

func RenderHook 

func RenderHook(fsys fs.FS, loop, host, timing string) (string, error)

RenderHook renders the hook shell for (loop, host, timing) from the embedded assets. It is the generator entry point: pure with respect to everything except assets.FS, which is compiled into the binary.

func RenderPayloadContract 

func RenderPayloadContract(fsys fs.FS, loop, skill string) (string, error)

RenderPayloadContract renders the payload-contract section for loops/<loop>/skills/<skill>: template.json supplies the teaching data, capability.LoadSpec the mechanical truth. It is the generator entry point — pure with respect to everything except assets.FS.

func RunClaudeProjector 

func RunClaudeProjector(ctx context.Context, action string, opts ClaudeOptions) error

func RunCodexProjector 

func RunCodexProjector(ctx context.Context, action string, opts CodexOptions) error

func ValidateGeneratedHooks 

func ValidateGeneratedHooks(hosts, loops []string) ([]string, error)

ValidateGeneratedHooks is the loop-validate-time gate for the generated hook surface: every (host, loop) pair must render ALL its declared timings cleanly. This catches what schema validation alone cannot — fragment files missing, host mechanics that no template combination supports, wording overrides nothing consumes — BEFORE an install would fail closed at projection time.

func WriteMemoryMirror 

func WriteMemoryMirror(path string, proj projection.Projection) error

Types

type ClaudeOptions 

type ClaudeOptions struct {
	ProjectRoot string
	Loops       []string
	HostArgs    []string
	Stdout      io.Writer
	Stderr      io.Writer
}

type CodexOptions 

type CodexOptions struct {
	ProjectRoot string
	Loops       []string
	HostArgs    []string
	Stdout      io.Writer
	Stderr      io.Writer
}

type ControlAction 

type ControlAction struct {
	Type string `json:"type"`
	// observe
	EventType        string `json:"event_type,omitempty"`
	ExternalIDPrefix string `json:"external_id_prefix,omitempty"`
	Payload          string `json:"payload,omitempty"`
	// pull-mirror
	MirrorVar  string `json:"mirror_var,omitempty"`
	MirrorPath string `json:"mirror_path,omitempty"`
}

ControlAction is one channel call inside a control-call section.

type HookGate 

type HookGate struct {
	Type string `json:"type"`
	// once-per-session-marker / two-phase-marker
	Marker string `json:"marker,omitempty"`
	// if-input-field
	Field string `json:"field,omitempty"`
	// threshold
	Metric       string `json:"metric,omitempty"`
	Cmp          string `json:"cmp,omitempty"`
	DirEnv       string `json:"dir_env,omitempty"`       // file-non-empty-lines: env var holding the directory
	File         string `json:"file,omitempty"`          // file-non-empty-lines: file name inside the directory
	FileEnv      string `json:"file_env,omitempty"`      // usage-event-count: env var holding the file path
	FileDefault  string `json:"file_default,omitempty"`  // usage-event-count: default file path expression
	LimitEnv     string `json:"limit_env,omitempty"`     // env var holding the limit
	LimitDefault string `json:"limit_default,omitempty"` // default limit value
}

HookGate is the union of all gate kinds; per-kind field checks keep the union closed (a field set on the wrong kind is an error, not silently ignored).

type HookIntents 

type HookIntents struct {
	SchemaVersion int                     `json:"schema_version"`
	Hooks         map[string]TimingIntent `json:"hooks"`
}

HookIntents is the decoded loops/<loop>/hooks/intents.json.

type HookResponse 

type HookResponse struct {
	Role  string `json:"role"`
	Text  string `json:"text,omitempty"`
	Over  string `json:"over,omitempty"`
	Under string `json:"under,omitempty"`
}

HookResponse carries the response role plus its wording slots: either a single text slot or a threshold-selected over/under pair (requires a threshold gate).

type HookSection 

type HookSection struct {
	Type string `json:"type"`
	// Glue attaches this section to the previous one without a blank separator line. Layout is
	// part of the byte-frozen target, and the legacy loops genuinely differ in it, so it is data.
	Glue bool `json:"glue,omitempty"`
	// env-prologue
	AssetDir    bool `json:"asset_dir,omitempty"`
	ProjectRoot bool `json:"project_root,omitempty"`
	// local-env-control
	ProjectRootLine bool `json:"project_root_line,omitempty"`
	// banner
	Lines []string `json:"lines,omitempty"`
	// control-call
	Comment        []string        `json:"comment,omitempty"`
	Actions        []ControlAction `json:"actions,omitempty"`
	WarnMissingBin bool            `json:"warn_missing_bin,omitempty"`
	// file-emit
	Var               string `json:"var,omitempty"`
	Path              string `json:"path,omitempty"`
	Header            string `json:"header,omitempty"`
	BlankBeforeHeader bool   `json:"blank_before_header,omitempty"`
	// include
	Fragment string `json:"fragment,omitempty"`
}

HookSection is the union of all section kinds (same closed-union discipline as HookGate).

type HostMechanics 

type HostMechanics struct {
	StdinRead  MechanicSelection `json:"stdin_read"`
	Dialect    MechanicSelection `json:"dialect"`
	JSONEscape bool              `json:"json_escape"`
	// MarkerOverrides[loop][timing] = false drops a marker gate the intents declare (e.g.
	// claude-code skill prime has no once-per-session marker).
	MarkerOverrides map[string]map[string]bool `json:"marker_overrides,omitempty"`
	// WordingOverrides[loop][timing][slot] replaces the canonical (codex) slot text.
	WordingOverrides map[string]map[string]map[string]string `json:"wording_overrides,omitempty"`
}

HostMechanics is the "mechanics" section of hosts/<host>/host.json: everything host-specific the generator needs. define != select — the enums and templates are compiled in; this data only selects among them.

type MechanicSelection 

type MechanicSelection struct {
	Default   string                       `json:"default"`
	Overrides map[string]map[string]string `json:"overrides,omitempty"`
}

MechanicSelection is a default enum value plus per-(loop,timing) overrides.

type ProjectContext 

type ProjectContext struct {
	Host        string
	ProjectRoot string
	Loops       []string
	HostArgs    []string
}

ProjectContext is the minimal context the background driver passes to ReProject: which host + loops to re-project, rooted at a project. The no-clobber policy applies (a pre-existing/edited file is preserved).

type Report 

type Report struct {
	Conflicts []string
}

Report is the outcome of a re-projection: the managed files preserved because the user edited them.

func ReProject 

func ReProject(ctx ProjectContext, refs []contract.ResourceRef) (Report, error)

ReProject re-projects the managed definition files for ctx under the no-clobber policy. It is the entrypoint the co-hosted background driver uses on an invalidation drain (Phase 3); refs names the resources whose projections may need refreshing (definition files do not depend on resource content, so they are always re-evaluated under the no-clobber policy).

func RunClaudeProjectorReport 

func RunClaudeProjectorReport(ctx context.Context, opts ClaudeOptions) (Report, error)

RunClaudeProjectorReport installs/re-projects the Claude Code projection under the no-clobber policy and returns the managed files it preserved because the user edited them.

func RunCodexProjectorReport 

func RunCodexProjectorReport(ctx context.Context, opts CodexOptions) (Report, error)

RunCodexProjectorReport installs/re-projects the Codex projection under the no-clobber policy and returns the managed files it preserved because the user edited them.

type TimingIntent 

type TimingIntent struct {
	Gates    []HookGate    `json:"gates,omitempty"`
	Sections []HookSection `json:"sections,omitempty"`
	Response *HookResponse `json:"response,omitempty"`
}

TimingIntent describes one lifecycle timing: gates that may short-circuit or parameterize the hook, an ordered section pipeline (prime), and the response (remind/nudge/compact).

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.