installspec

Documentation

Overview

Package installspec is the declarative KIDS install spec + validating loader (VSL T0a.3): the answers `v pkg install` feeds to a non-interactive KIDS install — the source distribution, the environment-check choice, the standard KIDS questions, and the device/queue. It is the JSON form of the install-spec.yaml in docs/kids-installation-automation.md §5. The standard answers map onto the KIDS XPDDIQ answer codes (XPO1/XPI1/XPZ1) used to suppress the prompts (see that doc, Tier A).

Index

• Constants
• func DeregisterScript(reg *PkgReg) string
• func FinalInstallScript(name, header string, nPairs int, runEnvCheck bool, ques []QuesAnswer, ...) string
• func HealDetectScript(name string) string
• func HealPurgeScript(name string) string
• func StageChunks(pairs []kids.Pair, maxBytes int) []string
• func UninstallScript(name string, routines []string, comps []kids.Component, files []string) string
• func VerifyContentScript(contents []kids.EntryContent, files []kids.FileContent) string
• func VerifyScript(name string, routines []string, comps []kids.Component, files []string) string
• type Answers
  • func (a Answers) XPDDIQ() map[string]string
• type Device
• type ExtraAnswer
• type PkgReg
• type QuesAnswer
• type Source
• type Spec
  • func Load(path string) (*Spec, error)
  • func Parse(data []byte) (*Spec, error)
  • func (s *Spec) Validate() error

Constants

const ResultMarker = "<<VPKG>>"

ResultMarker prefixes the script's machine-readable result lines on the principal device — the driver layer scans stdout for it. Format: `<<VPKG>>key=value`.

Functions

func DeregisterScript

func DeregisterScript(reg *PkgReg) string

DeregisterScript returns M that REMOVES the PACKAGE #9.4 patch-history footprint a prior `install --register-package` stamped — the inverse of FinalInstallScript's reg block, so $$PATCH^XPDUTL no longer reports the patch after a back-out. It finds the package by PREFIX (the "C" xref), the VERSION (#9.49) by value, and the PATCH APPLICATION HISTORY (#9.4901) entry by value, then FileMan-DIKs that entry (which also clears its "B" xref). It deliberately LEAVES the VERSION + package entries intact — they may carry other patches or be national, and KIDS itself never removes a package; the confirmed gap is only the $$PATCH ghost. A nil reg, or one with no patch (no patch-history entry exists), writes nothing.

func FinalInstallScript

func FinalInstallScript(name, header string, nPairs int, runEnvCheck bool, ques []QuesAnswer, reg *PkgReg) string

func HealDetectScript

func HealDetectScript(name string) string

HealDetectScript returns READ-ONLY M source that probes a #9.7 INSTALL entry for the half-install-corruption signal (kids-installation-automation.md §7.1): a prior aborted install can leave the "B" xref (so the re-install guard falsely reports already-installed) but no usable 0-node / a status that never reached 3. It emits the IEN, whether the 0-node exists, and the status (piece 9) as ResultMarker lines; the Go side grades them (classifyHeal). It mutates nothing — the purge is a separate, guarded step (HealPurgeScript).

func HealPurgeScript

func HealPurgeScript(name string) string

HealPurgeScript returns M source that purges a PROVEN-corrupt #9.7 entry by IEN so a clean reinstall can proceed: the entry subtree (which carries the "ASP"/"INI"/ "INIT" subnodes a half-install wrote), the "B" + "ASP" cross-references, and the staged ^XTMP("XPDI",ien) transport global (§7.1's documented manual purge — DIK cannot clean an entry whose 0-node is gone). Heal is a TARGETED repair, never a blanket force-delete: the script re-confirms corruption engine-side and REFUSES a healthy (status 3) entry, so a healthy install can never be purged even if the Go side were wrong about the state. Removing a healthy install is uninstall's job.

func StageChunks

func StageChunks(pairs []kids.Pair, maxBytes int) []string

StageChunks renders the transport-global pairs as M routine bodies that populate the staging global ^XTMP("VPKGI",…). Each body is kept at or below maxBytes (a lone over-long SET is its own chunk), so no single staged routine is large enough to hit the driver's silent-truncation limit. The first body clears any stale staging global. Run each body in order; the global persists across the (stateless) driver processes, accumulating the whole tree.

func UninstallScript

func UninstallScript(name string, routines []string, comps []kids.Component, files []string) string

UninstallScript returns M source that reverses an install (T0a.4): delete each routine (^%ZOSF("DEL") removes the .m + .o), each entry COMPONENT record from its storage file (FileMan DIK by the IEN resolved from the "B" index — clears its xrefs and any compiled subfiles), each FileMan FILE (its DD, data global, and dict-of-files pointer — KIDS ships no generic file uninstall), and the #9.7 INSTALL and #9.6 BUILD entries via DIK. The component deletes are driven generically from the kids.Component registry (one `^DIK` per shipped record, keyed on the type's storage global), so a new component type needs no change here — closing the orphan-on-uninstall gap for every registered type. The monotonic #9.x and per-file FileMan IEN counters are not rolled back (inherent to FileMan, not a leak).

func VerifyContentScript

func VerifyContentScript(contents []kids.EntryContent, files []kids.FileContent) string

VerifyContentScript returns M that reads back the LIVE 0-node of each shipped KRN entry record so `verify` can assert CONTENT, not just presence: per record it resolves the site IEN via the data file's "B" index, then writes the stored 0-node as a `z:<file>:<name>` marker (empty when the record is absent). The Go side compares each against the shipped image (kids.ZeroMatch), skipping the FileMan-transformed pieces. Reading the literal stored node (not the DBS API) is deliberate: it is the same image the KRN transport shipped, so a byte difference is a real filing fault.

func VerifyScript

func VerifyScript(name string, routines []string, comps []kids.Component, files []string) string

VerifyScript returns M source that reports whether name is installed: the #9.7 INSTALL presence + status (piece 9; 3 = "Install Completed"), per routine whether it is loaded ($T probe), per entry COMPONENT whether a record by that .01 NAME is present in its storage file's "B" index, and per FileMan FILE whether its data dictionary installed (^DD(file,0) present). Each fact is a ResultMarker line. The component probes are driven generically from the kids.Component registry (one `comp:<file>:<name>` marker per shipped record), so a new component type needs no change here.

Types

type Answers

type Answers struct {
	RebuildMenuTrees        bool `json:"rebuildMenuTrees"`
	InhibitLogons           bool `json:"inhibitLogons"`
	DisableOptionsProtocols bool `json:"disableOptionsProtocols"`
	DelayInstallMinutes     int  `json:"delayInstallMinutes"`
}

Answers are the four standard KIDS install questions.

func (Answers) XPDDIQ

func (a Answers) XPDDIQ() map[string]string

XPDDIQ maps the standard answers onto the KIDS XPDDIQ answer codes (set in the environment-check to suppress the prompts): XPO1 = rebuild menu trees, XPI1 = inhibit logons, XPZ1 = disable options/protocols. "0" = NO, "1" = YES.

type Device

type Device struct {
	Queue bool   `json:"queue"`
	At    string `json:"at,omitempty"` // ISO time when queued
}

Device selects the install output device / queueing.

type ExtraAnswer

type ExtraAnswer struct {
	PromptContains string `json:"promptContains"`
	Answer         string `json:"answer"`
}

ExtraAnswer answers a build-specific pre/post-install question by prompt match.

type PkgReg

type PkgReg struct {
	Prefix  string
	Name    string
	Version string
	Patch   string
}

FinalInstallScript returns the constant-size install routine run after StageChunks has populated ^XTMP("VPKGI",…). nPairs is the expected staged-node count: the routine counts the staging global and refuses to install if it does not match (so a silently-truncated stage fails loudly instead of installing a partial package). header is the #9.7 install header (cosmetic). ques pre-answers the build's install questions (A.1.3) so pre/post routines read them via $$ANSWER^XPDIQ. PkgReg is an optional PACKAGE #9.4 registration: the footprint a build writes so downstream $$VER/$$PATCH^XPDUTL checks see the install. Prefix is the #9.4 PREFIX (the namespace), Name the #9.4 .01 long NAME (used to create the entry when it is absent), Version/Patch the install's version + patch. A nil *PkgReg writes no footprint (matching a "NO package" build).

type QuesAnswer

type QuesAnswer struct {
	Name  string // question name — the $$ANSWER^XPDIQ(name) lookup key
	Value string // internal answer value $$ANSWER^XPDIQ returns
}

QuesAnswer is one pre-answered KIDS install question (A.1.3): the question NAME (the build's #9.6 QUES .01, looked up by ENV/pre/post code via $$ANSWER^XPDIQ) and its INTERNAL answer value. It is seeded into the #9.7 INSTALL record's internal "QUES" scratch tree so the non-interactive direct-populate path answers build-specific questions that the interactive question phase (skipped here) would.

type Source

type Source struct {
	Kind string `json:"kind"` // "hfs" (Host File) | "packman" (MailMan message)
	Path string `json:"path"`
}

Source is the distribution location.

type Spec

type Spec struct {
	Name         string        `json:"name"`                       // INSTALL NAME, e.g. ZZSKEL*1.0*1
	Source       Source        `json:"source"`                     // where the distribution comes from
	EnvCheck     string        `json:"environmentCheck,omitempty"` // "run" (default) | "skip"
	Backup       bool          `json:"backupTransportGlobal,omitempty"`
	Answers      Answers       `json:"answers"`
	Device       Device        `json:"device"`
	ExtraAnswers []ExtraAnswer `json:"extraAnswers,omitempty"` // build-specific pre/post questions
}

Spec is one install spec (kids/<pkg>.install.json or passed inline).

func Load

func Load(path string) (*Spec, error)

Load reads + validates an install spec from a file.

func Parse

func Parse(data []byte) (*Spec, error)

Parse decodes an install spec from JSON (rejecting unknown fields) + validates.

func (*Spec) Validate

func (s *Spec) Validate() error

Validate checks the spec is usable for a non-interactive install.