Documentation
¶
Overview ¶
Package project manages on-disk project entries at `<BaseDir>/projects/<id>/` (managed) or any user-supplied absolute path (custom).
A Project is a bundle of: 1 folder (the agent cwd), defaults (preset/provider/system_addon), pinned sessions, icon, and display name. Sessions reference a project via Meta.ProjectID.
Storage layout:
projects/<id>/ meta.json — project meta (this package owns it) files/ — managed cwd (only when CustomPath is empty)
Index ¶
- Constants
- func CanAccess(meta Meta, acc Access) bool
- func Delete(layout config.Layout, id string) error
- func EnsureDefault(layout config.Layout, newID func() string) error
- func Exists(layout config.Layout, id string) bool
- func FindPersonalProject(layout config.Layout, userID string) (string, error)
- func IsProtected(meta Meta) bool
- func List(layout config.Layout) ([]string, error)
- func ListVisibleTo(layout config.Layout, acc Access) ([]string, error)
- func MigrateWorkspacesToProjects(layout config.Layout, newID func() string, ...) error
- func RelinkSessions(layout config.Layout, wsName, projectID string) error
- func ResolvePath(layout config.Layout, id string) (string, error)
- func RewriteProvider(layout config.Layout, oldKey, newKey string) (int, error)
- func SaveMeta(layout config.Layout, id string, meta Meta) error
- type Access
- type AutoCreateRule
- type CreateOptions
- type Defaults
- type Meta
- type Project
- type TicketConfig
- func (c TicketConfig) ActiveWebhooks(event string) []TicketWebhook
- func (c TicketConfig) FirstStatus() string
- func (c TicketConfig) HasStatus(key string) bool
- func (c TicketConfig) StatusKeys() []string
- func (c TicketConfig) StatusLabel(key string) string
- func (c TicketConfig) StatusList() []TicketStatus
- func (c TicketConfig) TerminalStatus() string
- type TicketField
- type TicketIntegrations
- type TicketStatus
- type TicketWebhook
Constants ¶
const ( ChannelKindAny = "" ChannelKindDM = "dm" ChannelKindChannel = "channel" ChannelKindThread = "thread" )
Channel kinds an AutoCreateRule can be narrowed to. A DM is somebody's private conversation, so "track everything from Slack except DMs" has to be expressible as one rule rather than a list of channels.
const ( StatusOpen = "open" StatusInProgress = "in_progress" StatusWaiting = "waiting" StatusDone = "done" )
Built-in status keys. A project that never edits its statuses uses exactly these, so existing tickets keep working unchanged.
const DefaultName = "default"
DefaultName is the name of the built-in project that ships with every fresh install.
const PersonalTag = "personal"
PersonalTag marks the project auto-created for a user as their permanent default. It's the explicit, self-documenting flag used by IsProtected to keep the project undeletable — clearer than inferring "personal" from the owner field or the 👤 icon (which a user could change).
Variables ¶
This section is empty.
Functions ¶
func CanAccess ¶ added in v0.25.0
CanAccess reports whether meta is visible to acc. Mirrors the Service.CanAccessTool rule (admin bypass, untagged = open, otherwise tag match) and adds the project owner rule. Checked in order:
- admins/owners see every project
- a project with no owner and no tags is shared (everyone)
- the owner sees their own project
- a user carrying any of the project's tags sees it (tag share)
func Delete ¶
Delete removes the project metadata folder. For managed projects: also removes projects/<id>/ (including files/). For custom projects: the external folder is NOT touched.
Two projects are protected from deletion:
- the built-in "default" project (matched by name)
- any personal project (one carrying the PersonalTag) — the project auto-created for a user is their permanent default and cannot be removed. Use IsProtected to check this without attempting a delete.
func EnsureDefault ¶
EnsureDefault creates the "default" project if no projects exist yet. Called from Bootstrap after migration so fresh installs always have a usable project.
func FindPersonalProject ¶ added in v0.17.0
FindPersonalProject returns the project ID owned by userID, or "" if none exists. It scans all projects on disk looking for a matching OwnerUserID field.
func IsProtected ¶ added in v0.28.2
IsProtected reports whether meta names a project that cannot be deleted: the built-in "default" project (matched by name), or a personal project (one carrying PersonalTag — the auto-created per-user default). The UI uses this to hide/disable the delete control.
func ListVisibleTo ¶ added in v0.25.0
ListVisibleTo returns the IDs of projects acc may see, sorted like List. Use this for every user-facing project enumeration (channel default dropdown, pickers) instead of List, which returns all projects on disk.
func MigrateWorkspacesToProjects ¶
func MigrateWorkspacesToProjects(layout config.Layout, newID func() string, relink func(wsName, projectID string) error) error
MigrateWorkspacesToProjects is idempotent: it is a no-op when any project already exists on disk. Converts each workspace into a project with the same name, folder, and defaults, then relinks all sessions from workspace name to project_id.
Safety:
- Skips entirely if projects/ is non-empty.
- os.Rename is used for managed files/ — atomic on same-FS.
- Session meta is written only after the project is created.
- Legacy workspaces/ dir is kept on disk (not deleted) for safety.
func RelinkSessions ¶
RelinkSessions is the concrete relink callback used at boot: scans all session dirs and updates meta.project_id for sessions that reference the old workspace name. Uses a raw map round-trip to preserve all existing fields.
func ResolvePath ¶
ResolvePath returns the cwd for agent subprocesses bound to this project. Custom paths win; managed falls back to projects/<id>/files/.
func RewriteProvider ¶ added in v0.28.1
RewriteProvider re-points every project whose Defaults.Provider equals oldKey to newKey, persisting each change. Used when a provider instance is renamed so project defaults follow the new "type/name" automatically (live sessions are intentionally left alone — they keep the old key and must be re-pointed by the user). Returns the number of projects updated. A best-effort op: a single project's load/save failure is logged via the returned error only if EVERY candidate failed; partial success still returns the count of those that saved.
Types ¶
type Access ¶ added in v0.25.0
Access carries the caller identity used to filter project visibility. Build it in the handler from the request context so this package keeps no login/http imports:
project.Access{
UserID: user.ID,
TagIDs: login.GetUserTagIDs(ctx),
IsAdmin: user.IsAdmin(),
}
type AutoCreateRule ¶ added in v0.40.0
type AutoCreateRule struct {
// Origin scopes the rule to where the session came from: "ui",
// "slack", "telegram", "rest", … or "*" for any.
Origin string `json:"origin"`
// ChannelKind narrows a channel-origin rule to dm / channel / thread.
// Empty means any. Ignored for non-channel origins.
ChannelKind string `json:"channel_kind,omitempty"`
// Match is an optional text condition on the session's first message:
//
// "" — origin alone decides
// contains:<text> — case-insensitive substring
// regex:<expr> — Go regular expression
//
// A regex that does not compile is refused when the config is saved,
// rather than silently never matching.
Match string `json:"match,omitempty"`
// Enabled lets a rule be parked without losing how it was written.
Enabled bool `json:"enabled"`
// Title optionally templates the new ticket's title. "{message}" is
// replaced with the first message (truncated), "{origin}" with the
// origin. Empty falls back to the message itself.
Title string `json:"title,omitempty"`
}
AutoCreateRule is one condition under which a session is given a ticket.
type CreateOptions ¶
type CreateOptions struct {
ID string // pre-assigned UUID; generated if empty
Name string
Icon string
Description string
CustomPath string
Defaults Defaults
Tags []string
OwnerUserID string
Widget config.WidgetPolicy
}
CreateOptions describes a new project.
func PersonalProjectOptions ¶ added in v0.17.0
func PersonalProjectOptions(newID, userID, displayName string) CreateOptions
PersonalProjectOptions returns CreateOptions pre-filled for a personal project owned by userID. The caller is responsible for generating a unique ID and calling Create (or the registry manager's CreateProject) with the result.
type Defaults ¶
type Defaults struct {
Preset string `json:"preset,omitempty"`
Provider string `json:"provider,omitempty"`
// Model pins which model on Provider this project runs, in that
// instance's own id space — for wick that is "<entryID>@<vendorModelID>",
// i.e. down to the leaf of a live set.
//
// Meaningless without Provider, and never applied across a provider
// change: a pin belongs to the instance it was chosen on. Empty means
// "let the instance pick its own default", which is a real choice and
// not a missing value.
Model string `json:"model,omitempty"`
SystemAddon string `json:"system_addon,omitempty"`
}
Defaults holds the preset/provider/model/system_addon that new sessions in this project inherit when not explicitly overridden.
type Meta ¶
type Meta struct {
ID string `json:"id"`
Name string `json:"name"`
Icon string `json:"icon,omitempty"`
Description string `json:"description,omitempty"`
CustomPath string `json:"custom_path,omitempty"`
Defaults Defaults `json:"defaults"`
PinnedSessions []string `json:"pinned_sessions,omitempty"`
Tags []string `json:"tags,omitempty"`
OwnerUserID string `json:"owner_user_id,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
// Widget is this project's HTML-artifact CSP override. Zero value
// (Override false) means "inherit the global policy", which is what
// every meta.json written before this field decodes to — so no
// migration is needed. Resolve it with config.Resolve.
Widget config.WidgetPolicy `json:"widget,omitempty"`
// Ticket is this project's ticket-mode configuration. Zero value =
// off (see TicketConfig) — sessions stay plain chat sessions.
Ticket TicketConfig `json:"ticket,omitempty"`
}
Meta is the persisted shape of a project.
type Project ¶
type Project struct {
Meta Meta `json:"meta"`
}
Project is the in-memory view: meta only (no session list — that lives in the registry).
func Create ¶
func Create(layout config.Layout, opt CreateOptions) (Project, error)
Create materialises the on-disk project entry. For managed projects (CustomPath=="") it also creates projects/<id>/files/. Custom paths are not created — they must already exist.
func (Project) ResolveWidget ¶ added in v0.38.2
func (p Project) ResolveWidget(global config.GeneralConfig) config.WidgetPolicy
ResolveWidget returns the effective widget CSP policy for this project: the global policy when the project does not override it, otherwise the project's own modes with its allowlist appended to the global one. See config.Resolve for the exact semantics.
type TicketConfig ¶ added in v0.40.0
type TicketConfig struct {
Enabled bool `json:"enabled,omitempty"`
Fields []TicketField `json:"fields,omitempty"`
// Statuses are this project's board columns, in order. Empty means the
// built-in set (DefaultTicketStatuses) — which is what every project
// configured before statuses were editable decodes to.
Statuses []TicketStatus `json:"statuses,omitempty"`
// FollowupAfterSec: a non-done ticket untouched for this long is
// stale — the sweeper wakes the session's agent with FollowupPrompt
// (a system info turn, not a user message) and the agent decides
// what to do. Repeats every window while the ticket stays stale.
FollowupAfterSec int64 `json:"followup_after_sec,omitempty"`
FollowupPrompt string `json:"followup_prompt,omitempty"`
// AutoResolveAfterSec: a non-done ticket untouched for this long is
// closed — status set to done by the sweeper, no agent spawn.
AutoResolveAfterSec int64 `json:"auto_resolve_after_sec,omitempty"`
// AutoCreate decides when a new session gets a ticket of its own with
// nobody asking for one. Empty = off, which is what every project
// starts as. Rules are tried in order and the FIRST match wins, so a
// narrow exception belongs above the broad rule it carves out of.
AutoCreate []AutoCreateRule `json:"auto_create,omitempty"`
// Integrations wires the board to the outside world — outbound webhooks
// and the token-authed REST surface. Zero value = both off.
Integrations TicketIntegrations `json:"integrations,omitempty"`
}
TicketConfig turns a project's sessions into ticket cards. The zero value means the feature is off — every meta.json written before this field existed decodes to off, so no migration is needed.
Durations are plain seconds (not time.Duration) so the JSON contract with the settings UI stays a bare number. 0 = that automation is off.
func (TicketConfig) ActiveWebhooks ¶ added in v1.2.9
func (c TicketConfig) ActiveWebhooks(event string) []TicketWebhook
ActiveWebhooks returns the enabled webhooks that want event name.
func (TicketConfig) FirstStatus ¶ added in v0.40.1
func (c TicketConfig) FirstStatus() string
FirstStatus is where a new ticket lands when none was given.
func (TicketConfig) HasStatus ¶ added in v0.40.1
func (c TicketConfig) HasStatus(key string) bool
HasStatus reports whether key is one of this project's statuses.
func (TicketConfig) StatusKeys ¶ added in v0.40.1
func (c TicketConfig) StatusKeys() []string
StatusKeys returns just the keys, in board order.
func (TicketConfig) StatusLabel ¶ added in v0.40.1
func (c TicketConfig) StatusLabel(key string) string
StatusLabel returns a status's display label, falling back to its key so a board never draws a blank column header.
func (TicketConfig) StatusList ¶ added in v0.40.1
func (c TicketConfig) StatusList() []TicketStatus
StatusList returns the project's statuses, falling back to the built-in set. Read through this rather than the field: an empty list means "not customised", not "no columns", and a board with no columns would be a dead end.
func (TicketConfig) TerminalStatus ¶ added in v0.40.1
func (c TicketConfig) TerminalStatus() string
TerminalStatus is the stage that means the work is finished — what auto-resolve moves a ticket to, and what the followup timer treats as "leave it alone". Falls back to the last status when nothing is marked, which is the least surprising reading of a board's final column.
type TicketField ¶ added in v0.40.0
type TicketField struct {
Key string `json:"key"` // snake_case identifier, unique within the project
Label string `json:"label"` // shown in the card and the edit form
Type string `json:"type"` // "text" | "select"
Options []string `json:"options,omitempty"`
Required bool `json:"required,omitempty"`
}
TicketField is one custom field in a project's ticket schema. Values live per session in session.Meta.Ticket.Fields keyed by Key.
func DefaultTicketFields ¶ added in v0.40.0
func DefaultTicketFields() []TicketField
DefaultTicketFields returns the schema seeded when a project enables ticket mode with no fields configured yet.
type TicketIntegrations ¶ added in v1.2.9
type TicketIntegrations struct {
// APIEnabled opens the ticket REST endpoints to Personal Access Token
// auth for this project. Off by default: the board is reachable from
// the browser either way, and a project should have to opt in before a
// bearer token can move its work.
APIEnabled bool `json:"api_enabled,omitempty"`
// Webhooks are the endpoints notified when this project's tickets
// change. Order is display order only.
Webhooks []TicketWebhook `json:"webhooks,omitempty"`
}
TicketIntegrations wires a project's board to the outside world: outbound webhooks that fire when a ticket changes, and a token-authed REST surface so another system can create and move tickets.
The zero value means both are off, so every meta.json written before this field existed decodes to "no integrations" and nothing starts talking to the network because of an upgrade.
type TicketStatus ¶ added in v0.40.1
type TicketStatus struct {
Key string `json:"key"`
Label string `json:"label,omitempty"`
// Terminal marks the stage that means the work is over. Exactly one
// status carries it.
Terminal bool `json:"terminal,omitempty"`
}
TicketStatus is one column on a project's board.
Statuses are per project because what a team calls its stages is theirs to name — "triage → coding → review → shipped" is as valid as the defaults. Two things are structural rather than cosmetic:
- Key is what a ticket stores and what the MCP surface accepts. It is stable; Label is what the board draws and can be reworded freely.
- Exactly one status must be Terminal. The stale-followup and auto-resolve timers need to know which stage means "finished", or a sweeper would nag tickets that are already done and auto-resolve would have nowhere to move them.
func DefaultTicketStatuses ¶ added in v0.40.1
func DefaultTicketStatuses() []TicketStatus
DefaultTicketStatuses is the set a project starts with.
type TicketWebhook ¶ added in v1.2.9
type TicketWebhook struct {
// ID is stable across edits so a delivery log can be kept per webhook
// even as its URL or name is reworded.
ID string `json:"id"`
Name string `json:"name,omitempty"`
URL string `json:"url"`
// Secret keys the HMAC-SHA256 signature sent as X-Wick-Signature. Empty
// means unsigned — allowed (a receiver on a private network may not
// need it) but the UI nudges against it.
//
// Never rendered back to a client: the API redacts it on read, and a
// blank value on save means "keep the stored one" rather than "clear
// it", so editing a webhook's URL cannot silently unsign it.
Secret string `json:"secret,omitempty"`
// Events filters which events reach this endpoint. Empty means all of
// them, which is the least surprising default for a fresh webhook.
Events []string `json:"events,omitempty"`
// Headers are extra request headers, for receivers that need a static
// API key or a routing hint alongside the signature.
Headers map[string]string `json:"headers,omitempty"`
// Enabled parks an endpoint without losing how it was configured.
Enabled bool `json:"enabled"`
}
TicketWebhook is one outbound endpoint.
func (TicketWebhook) WantsEvent ¶ added in v1.2.9
func (w TicketWebhook) WantsEvent(name string) bool
WantsEvent reports whether this webhook should receive event name.