Documentation
¶
Index ¶
Constants ¶
const AgentsFile = "AGENTS.md"
AgentsFile is the file in a module root that coding agents read first, which `sal edit --agents` writes the agent prompt into so that it never has to be pasted by hand. The form does not offer it: a module with the salmodule skill installed has the contract there already, and the prompt is for pasting into an agent once.
Variables ¶
var ErrForeignAgentsFile = errors.New(AgentsFile + " exists and was not written by sal; remove it or write the prompt elsewhere")
ErrForeignAgentsFile is returned when AGENTS.md exists and sal did not write it, since what it holds is someone's own instructions.
var ErrNotAModule = errors.New("the current directory is not a SAL module: it has no " + salmodule.OntologyFile + "; run `sal init --salmodule` to create one")
ErrNotAModule is returned when the current directory holds no ontology.jsonld, since there is nothing to edit.
Functions ¶
func AgentPrompt ¶
AgentPrompt renders the prompt a user hands a coding agent to implement the SAL module in dir from its ontology.jsonld: what the document declares, read out of the document itself, followed by the contract every module container keeps, where the SAL module agent skill is installed in the module (or how to install it), and how to test the result. The document is the source of truth and the prompt says so; what is listed here is so that the agent sees the tasks, their configuration, and their output shapes without reconstructing them from the JSON-LD.
func WriteAgentsFile ¶
WriteAgentsFile renders the agent prompt for the document and writes it as AGENTS.md in the module root, headed by the marker that lets sal write it again, refusing an AGENTS.md sal did not write. It returns the path.
Types ¶
type AgentsFileState ¶
type AgentsFileState string
AgentsFileState is what the module root holds under AgentsFile: nothing, a file sal wrote, or a file someone else wrote.
const ( AgentsFileNone AgentsFileState = "none" AgentsFileSal AgentsFileState = "sal" AgentsFileOther AgentsFileState = "other" )
type EditCmd ¶
type EditCmd struct {
Prompt bool `` /* 137-byte string literal not displayed */
Agents bool `` /* 146-byte string literal not displayed */
Port int `arg:"--port" help:"serve the form on this localhost port instead of an ephemeral one, for forwarding it over SSH"`
UI bool `` /* 146-byte string literal not displayed */
}
EditCmd opens the browser form that edits a SAL module's ontology.jsonld, the same form `sal init --salmodule` creates it with, in the module the current directory belongs to.
type Form ¶
type Form struct {
// Dir is the module root, where ontology.jsonld is written.
Dir string
// Namespace is the module's own salmodule:// namespace, which the checks
// resolve the ontology's relative terms against.
Namespace string
// Title and Creator seed a new ontology node, from the git remote and
// user.name like the prompts do.
Title string
Creator string
// Mode is the command that opened the form, "init" or "edit"; the page
// names itself after it.
Mode string
// Written is called after ontology.jsonld has been written, so the
// command can say so in its log.
Written func()
}
Form answers the module ontology form that `sal init --salmodule` and `sal edit` open in the browser. The form assembles ontology.jsonld, asks the server to check it as it is edited, and asks it to write the file; the server also tells the form what the module root holds, which it reads from disk on every request so that a file written or deleted by hand is seen without a restart. One server serves both commands: the only difference is Mode, which the page shows, and that `sal init` starts from a blank draft where there is no ontology yet while an existing one is loaded for editing.
func NewForm ¶
NewForm describes the module in dir for the form: its namespace from the git remote, and the title and creator a new ontology node starts with.
func (*Form) Handler ¶
Handler routes the form's JSON endpoints and serves the embedded page for everything else.
func (*Form) Problems ¶
Problems runs every check `sal validate --salmodule` would over the document, reported against the lines of the document itself.
func (*Form) Serve ¶
Serve serves the form on a localhost port until the process is interrupted, opening it in the browser unless openBrowser is false or no browser is likely to open. port 0 picks an ephemeral port, so that the form never collides with a `sal serve` on 8080 or with a second module being edited at the same time; a fixed one is for forwarding over SSH. The server keeps running once the file has been written, since the form edits as well as creates, until the user stops it.
type Problem ¶
Problem is one problem with the document the form assembled, on the line of the document the form showed, so the form can mark it there.
type Status ¶
type Status struct {
Mode string `json:"mode"`
// Initialized reports whether ontology.jsonld exists in the module root.
Initialized bool `json:"initialized"`
OntologyPath string `json:"ontologyPath"`
Namespace string `json:"namespace"`
Title string `json:"title"`
Creator string `json:"creator"`
// Document is the current text of ontology.jsonld, which the form edits
// from, or "" when there is none.
Document string `json:"document"`
// Dockerfile reports whether the module has a Dockerfile yet.
Dockerfile bool `json:"dockerfile"`
}
Status is what GET /api/module/status answers.