botinstall

Documentation

Overview

Package botinstall imports a bot bundle from a git URL or local path into a workspace so `iterion bots list`, the dispatcher, and the studio discover it. It is the shared core behind the `iterion bots install` CLI and the studio's POST /api/v1/bots/install endpoint — kept in a neutral package so pkg/server can reuse it without importing pkg/cli (which would cycle).

Installed bots are NEVER run automatically: the operator inspects, then launches (run-time sandboxing applies as usual).

Index

• func Fetch(ctx context.Context, opts Options) (dir string, cleanup func(), err error)
• func FetchRaw(ctx context.Context, opts Options) (dir string, cleanup func(), err error)
• func Remove(_ context.Context, opts Options) error
• type Metadata
  • func Inspect(ctx context.Context, opts Options) (*Metadata, error)
• type Options
• type PresetMeta
• type Result
  • func Install(ctx context.Context, opts Options) (*Result, error)
  • func InstallFromBotzBytes(ctx context.Context, r io.Reader, opts Options) (*Result, error)

Functions

func Fetch

func Fetch(ctx context.Context, opts Options) (dir string, cleanup func(), err error)

Fetch resolves opts.Source (a git URL or local path) to a validated bundle directory and returns its path plus a cleanup func. Unlike Install it is READ-ONLY: it never copies into a workspace, never regenerates a catalog, and never mutates the caller's tree. It is the materialization step behind the marketplace `.botz` download endpoint — the caller packs the returned directory with bundle.PackDir, then invokes cleanup() to drop the temp clone. For a local-path Source (e.g. a builtin entry's RepoURL) cleanup is a no-op and the returned path is the source dir itself, so callers MUST NOT mutate it.

func FetchRaw

func FetchRaw(ctx context.Context, opts Options) (dir string, cleanup func(), err error)

FetchRaw resolves opts.Source like Fetch but skips the bot-bundle discovery/validation: it returns the raw source tree, narrowed to opts.Path when set. It is the materialization step behind the marketplace download of non-bot entries (plugins, whose layout bundle.OpenDir would reject). Same read-only contract as Fetch: never mutate the returned directory.

func Remove

func Remove(_ context.Context, opts Options) error

Remove deletes an installed bot bundle (<workdir>/.botz/<name>) and refreshes Nexie's catalog. A missing install is an error so the caller can surface a 404. Mirrors Install's destination resolution.

Types

type Metadata

type Metadata struct {
	Name        string       `json:"name"`
	DisplayName string       `json:"display_name,omitempty"`
	Description string       `json:"description,omitempty"`
	Author      string       `json:"author,omitempty"`
	Version     string       `json:"version,omitempty"`
	Triggers    []string     `json:"triggers,omitempty"`
	Presets     []PresetMeta `json:"presets,omitempty"`
	README      string       `json:"readme,omitempty"`
}

Metadata is the bundle description Inspect extracts from a source repo without copying anything into a workspace. It is the registry-facing shape: enough to render a marketplace card + detail view, but a strict subset of bundle.Manifest + bundle.PresetSpec — fields not relevant to a registry preview are intentionally omitted.

func Inspect

func Inspect(ctx context.Context, opts Options) (*Metadata, error)

Inspect resolves Options like Install does — clones a git URL or uses a local directory in place, picks a bundle directory, validates it — and returns the bundle's metadata WITHOUT writing anything into a workspace destination. It powers the hosted marketplace's submit/refresh path: the operator points the registry at a repo, Inspect extracts the card metadata, and the entry is persisted. Install runs later, when a user asks to install that registry entry.

Only Options.Source, Options.Ref and Options.Path are honoured. Options.Dest, Options.Name, Options.Force and Options.Workdir are ignored (Inspect never copies anything anywhere).

type Options

type Options struct {
	Source  string // git URL (optionally url#ref) or a local directory
	Ref     string // git ref (branch/tag); overrides a #ref in Source
	Path    string // subdirectory within the repo, or an iterion-bots.yaml bot name
	Dest    string // install destination root (default <workdir>/.botz)
	Name    string // install under this name instead of the source's
	Force   bool   // overwrite an existing install
	Workdir string // workspace root for catalog regen (default cwd)
}

Options configures an install.

type PresetMeta

type PresetMeta struct {
	Name        string   `json:"name"`
	DisplayName string   `json:"display_name,omitempty"`
	Description string   `json:"description,omitempty"`
	Skills      []string `json:"skills,omitempty"`
}

PresetMeta is the registry-facing slice of bundle.PresetSpec: just the fields the marketplace card / detail view needs. The Prompt body and Vars map are deliberately dropped — they're only useful at run time and would bloat every registry entry.

type Result

type Result struct {
	Name          string `json:"name"`
	Source        string `json:"source"`
	Ref           string `json:"ref,omitempty"`
	InstalledPath string `json:"installed_path"`
	Skills        int    `json:"skills"`
	Presets       int    `json:"presets"`
}

Result is the structured outcome of an install.

func Install

func Install(ctx context.Context, opts Options) (*Result, error)

Install imports a bot bundle per Options and returns where it landed.

func InstallFromBotzBytes

func InstallFromBotzBytes(ctx context.Context, r io.Reader, opts Options) (*Result, error)

InstallFromBotzBytes extracts a `.botz` archive streamed from r into a temp dir, then installs it into the workspace exactly like Install: validate the bundle, copy it into <workdir>/.botz/<name>, refresh the catalog. The archive's manifest.name wins unless opts.Name overrides it; opts.Source/Ref/Path are ignored (the bytes are the source). This is the entry point behind the studio "Import .botz file" upload.