Documentation
¶
Overview ¶
Package harborinit ships the `harbor init` engine.
`harbor init` materialises a tiered, commented `harbor.yaml` plus three companion files (`AGENTS.md`, `CLAUDE.md`, `README.md`) into a target directory. The operator then edits the yaml — uncomments one of four LLM-provider example blocks, opts into built-in tools, adds MCP servers, tunes memory — and proceeds with `harbor validate` and `harbor scaffold`.
Phase 83n / D-153. The shape mirrors `cmd/harbor/scaffold`:
- Templates live under `cmd/harbor/init/templates/<name>/`.
- The default template is named `default` (V1.1 ships exactly one — a second template earns its keep when a real second use case arrives, not before).
- Files are rendered through `text/template` with `{.Name}` as the only variable.
The engine refuses to overwrite an existing file. A target directory that holds even one of the four files is rejected with `ErrFileExists` naming the offending path — the operator deletes the file (or picks a fresh `--target`) before retrying. This is the §13 fail-loud posture for an operator-facing seam.
Index ¶
Constants ¶
const DefaultTemplate = "default"
DefaultTemplate is the template `harbor init` selects when the operator omits --template. V1.1 ships only `default`.
Variables ¶
var ( // ErrInvalidName signals Options.Name failed validateName. ErrInvalidName = errors.New("init: invalid project name") // ErrFileExists signals one of the four files Init would write // already exists in the target directory. Operators delete the // file or pick a fresh target — Init refuses to overwrite. ErrFileExists = errors.New("init: target file already exists") // ErrUnknownTemplate signals the requested template does not // exist in the embedded tree. ErrUnknownTemplate = errors.New("init: unknown template") // ErrInitFailed wraps any rendering / write failure not covered // by the more specific sentinels above. ErrInitFailed = errors.New("init: render failed") )
Sentinel errors. Callers (`cmd/harbor/cmd_init.go::runInit`) compare via errors.Is and map onto the CLIError code surface.
Functions ¶
Types ¶
type Options ¶
type Options struct {
// Name is the agent name. Used as `.Name` inside templates so the
// rendered files refer to the operator's intended agent. When
// empty, Init derives the name from `filepath.Base(TargetDir)`;
// when the basename does not satisfy `validateName`, Init falls
// back to `"agent"` (the operator can rename freely after).
Name string
// Template selects which embedded template tree to render. Empty
// defaults to DefaultTemplate. The set of allowed values comes
// from Templates().
Template string
// TargetDir is the directory the four files are written into.
// Empty defaults to the current working directory. The directory
// is created (`os.MkdirAll`) if it does not exist; an existing
// directory is OK as long as none of the four target files
// already exist within it.
TargetDir string
}
Options is the input to Init.
type Result ¶
type Result struct {
Name string `json:"name"`
TargetDir string `json:"target_dir"`
Files []string `json:"files"`
}
Result reports what Init wrote. Files are absolute paths in deterministic (lexicographic) order.
func Init ¶
Init materialises the four templated files into opts.TargetDir.
Validation order (fail-loud, no partial writes):
- opts.Template (empty → DefaultTemplate) must be a registered template.
- opts.TargetDir is resolved via filepath.Abs and created if absent.
- opts.Name is normalised: explicit value validates via validateName; empty value falls back to the basename, and a non-validating basename falls back to the literal "agent".
- Each of the four target files MUST NOT already exist; the first collision returns ErrFileExists naming the path.
On success Result.Files is the sorted list of ABSOLUTE paths written.
Source Files