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 CanManage(meta Meta, userID string, isAdmin bool) 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 IsAgentProject(meta Meta) bool
- 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
- func SetShowInProjects(meta *Meta, on bool) bool
- func ShowsInProjects(meta Meta) bool
- func ValidID(id string) bool
- type Access
- type AutoCreateRule
- type CreateOptions
- type Defaults
- type Meta
- type Project
- type TicketButton
- type TicketConfig
- func (c TicketConfig) ActiveWebhooks(event string) []TicketWebhook
- func (c TicketConfig) ButtonByID(id string) (TicketButton, bool)
- func (c TicketConfig) ButtonsOn(placement string) []TicketButton
- func (c TicketConfig) CardFields(values map[string]string) map[string]string
- 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 ( ButtonOnTicket = "ticket" ButtonOnBoard = "board" )
Button placements — WHERE a custom button is drawn, and therefore what clicking it is about.
A ticket button acts on the one ticket whose page it sits on; a board button acts on the LIST the toolbar is filtering, and so carries the filter (who, which columns) instead of a single ticket. Two different questions, so they are two different events — see ticket.EventAction and ticket.EventBoardAction.
The empty string means ButtonOnTicket: every button saved before this field existed was a ticket-page button, and an upgrade must not move them onto the board.
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 AgentTag = "wick:team"
AgentTag marks a project the Team app made to hold an agent's persona (Captain included). Such a project is left out of the sidebar's Projects list; it stays reachable by URL and from the agent. A project an agent was pointed at by the user carries no tag and keeps showing.
Namespaced so a user's own "agent" label never hides their project. Project tags are not validated, so the ':' is safe.
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).
const VisibleTag = "wick:team-visible"
VisibleTag keeps an agent project (one carrying AgentTag) in the sidebar's Projects list as well. A tag rather than a meta field, so projects written before it decode to "hidden", as they always were.
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 CanManage ¶ added in v1.18.0
CanManage reports whether userID may change meta's settings or delete the project. Narrower than CanAccess on purpose: a tag grant lets a member work in the project (board, tickets, sessions) but not reconfigure or remove it — only its owner may. An ownerless project stays admin-only, the rule CanAccess's caller already applies to it.
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 IsAgentProject ¶ added in v1.2.9
IsAgentProject reports whether meta carries AgentTag.
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.
func SetShowInProjects ¶ added in v1.2.9
SetShowInProjects adds or drops VisibleTag. Returns whether meta changed.
func ShowsInProjects ¶ added in v1.2.9
ShowsInProjects reports whether meta is listed in the sidebar's Projects: every ordinary project, and an agent project only with VisibleTag.
func ValidID ¶ added in v1.16.0
ValidID reports whether id can name a project (or a ticket) on disk: one path segment — no separator, no "..", no leading dot, no "%", no control character, at most 128 bytes. Ids come from URLs and tool input, so a read checks it before joining id into a path; an id that fails is simply not found.
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 TicketButton ¶ added in v1.2.9
type TicketButton struct {
// ID is stable across edits, minted on first save. It travels in the
// event so a receiver serving several buttons can tell them apart.
ID string `json:"id"`
Label string `json:"label"`
URL string `json:"url"`
// Placement is ButtonOnTicket (default) or ButtonOnBoard.
Placement string `json:"placement,omitempty"`
}
TicketButton is one custom action, rendered either on a ticket's page or in the ticket list's toolbar (see Placement).
Clicking it POSTs an event envelope (the actor, this button's id, and either the full ticket or the list's filter) to URL and reports the response to the clicker. One label, one URL — anything smarter belongs in the receiver.
func (TicketButton) On ¶ added in v1.2.9
func (b TicketButton) On(placement string) bool
On reports whether this button belongs at placement, treating an empty Placement as ButtonOnTicket.
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,
// the token-authed REST surface, and the custom ticket buttons. Zero
// value = all 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) ButtonByID ¶ added in v1.2.9
func (c TicketConfig) ButtonByID(id string) (TicketButton, bool)
ButtonByID finds one of the project's ticket buttons.
func (TicketConfig) ButtonsOn ¶ added in v1.2.9
func (c TicketConfig) ButtonsOn(placement string) []TicketButton
ButtonsOn returns the project's buttons for one placement, in config order — what a page renders.
func (TicketConfig) CardFields ¶ added in v1.2.9
func (c TicketConfig) CardFields(values map[string]string) map[string]string
CardFields filters a ticket's field values down to what the board card draws: schema fields explicitly marked show_on_card, in no particular order (the client orders by schema). Values written outside the schema — the REST surface accepts any key — stay stored and stay on the ticket's page, but never reach a card: the board is a glance, not a record.
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"`
// ShowOnCard puts this field's value on the board card. Off by default:
// a card is a glance, and every chip on it is one more thing between the
// eye and the title. The full set is always on the ticket's own page.
ShowOnCard bool `json:"show_on_card,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"`
// Buttons are custom actions on a ticket's page ("Sync to Notion") or
// in the ticket list's toolbar ("Pull my tickets from Notion"), by
// their Placement. Clicking one POSTs to that button's URL — see
// TicketButton.
Buttons []TicketButton `json:"buttons,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.